From fd5801c3cf0485ba6da52758aa027d905724f96a Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 17 May 2023 13:38:19 -0500 Subject: [PATCH] Create markdown-asciidoc --- markdown-asciidoc | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 markdown-asciidoc diff --git a/markdown-asciidoc b/markdown-asciidoc new file mode 100644 index 0000000..88c112d --- /dev/null +++ b/markdown-asciidoc @@ -0,0 +1,39 @@ +==== IV. Comparison of text entry, editing, preview, publication, and CI/CD tools: Markdown-based vs Asciidoc-based + +[cols=3*,stripes=odd] +|=== +^| *FEATURE/ASPECT* ^|*MARKDOWN* ^| *ASCIIDOC* + +|Basic text entry, editing, and preview +|https://code.visualstudio.com/docs/languages/markdown[VS Code support for Markdown] +|https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[Asciidoc support for VS Code] + +| Distinguishing features +| Broad adoption, greater volume of published content, simple syntax for basic features, enhanced features available in various markdown flavors + +| Complex tables, asides, definition lists, includes, sidebars, table of contents, live snippets from source code, anchors, in-file metadata, attribute/variable support, ifdef/ifndef for conditional inclusion + +| Flavors and Standards +| Markdown (MD) plus varieties: Github Flavored Markdown (GFM), GitLab Flavored Markdown (GLFM, based on https://commonmark.org/[CommonMark]) +| Asciidoc specification is governed by the https://asciidoc-wg.eclipse.org/[Asciidoc Working Group] under Eclipse + +|Publication process +|Markdown -> Jekyll -> GitHub Pages + +Markdown -> Jekyll -> GitLab Pages + +Output: HTML, pdf, more via Pandoc +|Asciidoc -> https://antora.org/[Antora] -> GitLab Pages + +Asciidoc -> Antora -> GitHub Pages + +Output: HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI + +Multi-repository documentation sites via Antora + +|CI/CD support +|Jekyll to GitHub Pages via Github Actions; To GitLab pages via https://docs.gitlab.com/ee/user/markdown.html[GitLab Flavored Markdown] (based on Kramdown) + +|Antora to GitLab Pages via .gitlab-ci.yml playbook; to GitHub pages via Github Actions with .nojekyll directive + +|Conversion between markdown and asciidoc +|https://github.com/asciidoctor/kramdown-asciidoc[markdown to asciidoc] +|https://github.com/opendevise/downdoc[asciidoc to markdown] + +| +|HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI + +|===