The case for asciidoc from the asciidoctor folks, quoted liberally from AsciiDoc vs Markdown for purposes of discussion and analysis (i.e. Fair Use):
"The defacto lightweight markup language is Markdown. (At least, that’s what you call it at first). The
main advantage of Markdown lies in its primitive syntax: its manual and cheatsheet are one and the
same. But this advantage is also its greatest weakness.
As soon as authors need something slightly more complex than basic prose (e.g., tables, cross
references, footnotes, embedded YouTube videos, etc.), they find themselves resorting to embedded
HTML or seeking out more feature-rich implementations. Markdown has become a maze of different
implementations, termed “flavors”, which make a universal definition evasive.
The IETF has declared “there is no such thing as "invalid" Markdown.” See This Is Markdown!
Or: Markup and Its Discontents.
Here’s how the story inevitably goes. You start out with Markdown. Then it’s Markdown + X. Then
Markdown + X + Y. And down the rabbit hole you go. What’s worse, X and Y often require you to
sprinkle in HTML, unnecessarily coupling content with presentation and wrecking portability. Your
instinct to choose Markdown is good. There are just better options.
AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as
concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without requiring the
use of HTML or “flavors” for essential syntax such as tables, description lists, admonitions (tips, notes,
warnings, etc.) and table of contents.
It’s important to understand that AsciiDoc was initially designed as a plain-text alternative to the
DocBook XML schema. AsciiDoc isn’t stuck in a game of whack-a-mole trying to satisfy publishing
needs like Markdown. Rather, the AsciiDoc syntax was explicitly designed with the needs of publishing
in mind, both print and web. If the need arises, you can make full use of the huge choice of tools
available for a DocBook workflow using Asciidoctor’s DocBook converter. That’s why mapping to an
enterprise documentation format like DocBook remains a key use case for AsciiDoc.
And yet, AsciiDoc is simple enough to stand in as a better flavor of Markdown. But what truly makes
AsciiDoc the right investment is that its syntax was designed to be extended as a core feature. This
extensibility not only means that AsciiDoc has a lot more to offer, with room to grow, it also fulfills the
objective of ensuring your content is maximally reusable."
