FYI, for an in-depth analysis of
Markdown vs similar
Asciidoc and
reStructuredText text-based markups see the following article:
In the first part of my docs-as-code series, I'll talk about the choice of markup languages, the available frameworks, and do a comparison among Markdown (md), Asciidoc (adoc), and reStructuredText (rST) based on some use cases. [...] My hope is to provide you with a detailed analysis of these choices of markup languages so that you can make an informed decision when selecting one for your next developer documentation project.
Incidentally, the Open Web Documentation project switched from
HTML to
Markdown last year and you can now find a motivation explainer on their site:
In 2021, the Open Web Docs team, with help from Mozilla, the W3C, and the wider web docs community, converted the authoring format for MDN Web Docs -- all 11,000 pages of it -- from HTML to Markdown.
Here's somewhat of a contrarian viewpoint regarding
Markdown:
I truly loathe Markdown. Truly. But given the widespread use of Markdown, it might seem strange that I have such aversion to it. If you somehow really like it, or are so used to it by now, you might be tempted to think I'm the oddball.
And, BTW, the
CommonMark spec is currently at v0.30, released 2021-06-19 (cf.
https://spec.commonmark.org/).