Skip to content
Permalink
chubing
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

iam-knowledge-bits/markdown-asciidoc.adoc

Go to file
@khazelton
khazelton Rename markdown-asciidoc to markdown-asciidoc.adoc
Latest commit e6baeaa May 17, 2023 History
1 contributor

Users who have contributed to this file

39 lines (30 sloc) 1.95 KB
Raw Blame

IV. Comparison of text entry, editing, preview, publication, and CI/CD tools: Markdown-based vs Asciidoc-based

FEATURE/ASPECT MARKDOWN ASCIIDOC

Basic text entry, editing, and preview

VS Code support for Markdown

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 CommonMark)

Asciidoc specification is governed by the Asciidoc Working Group under Eclipse

Publication process

Markdown → Jekyll → GitHub Pages
Markdown → Jekyll → GitLab Pages
Output: HTML, pdf, more via Pandoc

Asciidoc → 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 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

markdown to asciidoc

asciidoc to markdown