From 93a1d7b1e6104559ffcb5904f1aa6977cfd53ae9 Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 17 May 2023 13:37:18 -0500 Subject: [PATCH] Update docToolRec.adoc --- docToolRec.adoc | 42 +----------------------------------------- 1 file changed, 1 insertion(+), 41 deletions(-) diff --git a/docToolRec.adoc b/docToolRec.adoc index eef3fa6..5a074ea 100644 --- a/docToolRec.adoc +++ b/docToolRec.adoc @@ -12,7 +12,7 @@ _2023-05-14 13:48:53 Draft documentation tool option comparisons_ What features of Confluence are used in our wiki content? Are there counterparts in the other options under consideration? -Specific Items +Specific Requirements . A documentation entry system with source files under version control . A process that creates a web accessible documentation site from the source repository @@ -35,8 +35,6 @@ Specific Items .. Substitutes punctuations with typographic entities .. Github emojis - - ==== III. Static site generators as documentation substrate . MkDocs @@ -47,42 +45,4 @@ Specific Items . Antora . Hugo -==== 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 -|===