Skip to content

Markdown vs. Asciidoc

Within the open source community, Markdown has become the winner in terms of widespread use and integration into tools and platforms.

  • Apart from Asciidoc, reStructuredText is another contender: it is widely used in the Python community, but not so much elsewhere, so I have not considered it here.
  • I also looked at options to generate a website from my Zim notes. It is possible to export Zim notes as a website, or as reStructuredText (it is a Python app), but neither seemed to be a viable route to me.

Comparison

When working on an earlier assignment (around 2016-2018), we were looking at plain-text markup formats, and tools to generate websites.

This is my comparison of Markdown versus Asciidoc back then, with a few updates for my situation in 2025.

Aspect Markdown Asciidoc
Format Both have a simple text-based format that is are very suitable for version control. Both have a simple text-based format that is are very suitable for version control. The syntax takes a bit more time to get used to.
Standardisation There is no single Markdown standard. Each variation adds features in their own way.1 Asciidoc is turning into an open standard, and is supposedly semantically equivalent to DITA. It offers many useful standard features.
Document meta data Common practice is to include YAML-based "front matter" to specify meta data. Documents have a title, followed by meta data attributes.
Document features Markdown is deliberately limited to keep it simple. There are extensions to include the ability to work with tables or formulas.

It is possible to include CSS classes, but these will not be shown in a WYSIWYG editor.		 Asciidoc supports more complex markup, such as footnotes, (nested) tables, and semantic markup, for instance for admonitions.
HTML support Both formats allow including HTML code for further layout.

In Markdown, this can be directly included.		 Both formats allow including HTML code for further layout.

In Asciidoc, this needs to be put in a pass-thru block.
Text editing Most editors offer Markdown plugins with a "preview" to see the visual result. Users edit the raw text markup, with the help of syntax highlighting. Most editors offer Asciidoc plugins with a "preview" screen or tab to see the visual result. Users edit the raw text markup, with the help of syntax highlighting.
In-place WYSIWYG editors - Obsidian
- Typora
- Zettlr		 none
Diagram support Most WYSIWYG editors support Mermaid of the box.

PlantUML can be included too.		 Mermaid and PlantUML can be included.
Writing documents Markdown is indeed a simple format, and "real WYSIWYG" editors like Typora make writing easy.

However, it lacks for instance more sophistcated tables with row or column spans (unless you resort to HTML).		 The Asciidoc documentation has a section title "Graduating to Asciidoc".

It offers advanced features, but also requires me to more often check with the documentation (or a preview).
Collaboration Markdown is the easier format and more popular.

However, for it does require additional agreements on the exact flavour to use, to work with tables, definition lists, and so on.		 Smaller edits in Asciidoc are easy, but a contributor will likely need the documentation at hand for anything more elaborate.
Conversion Pandoc is not able to read Asciidoc, so converting to Markdown requires extra work. Pandoc is able to convert Markdown into Asciidoc out of the box.

Choice

In my earlier assignment, it made sense to choose Asciidoc. However, since then, the more popular Markdown, combined with useful WYSIWYG editors, have won me over.

Obsidian, as my primary editor, also offers benefits in my general editing and task management workflow, that make the choice even more compelling.

  1. Comparison of features in various Markdown flavors. (n.d.). Retrieved 26 July 2025, from https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f#file-markdown-flavors-md
     ↩

  2. Holscher, E. (2016, March 15). Why You Shouldn’t Use “Markdown” for Documentation. https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
     ↩

  3. Setter, M. (2019, May 16). Convert Markdown to AsciiDoc The Right Way! Use Kramdoc. https://matthewsetter.com/technical-documentation/asciidoc/convert-markdown-to-asciidoc-with-kramdoc/
     ↩