[ethanwillis]

This is both the power and "problem" with Markdown. The "promise" (I'd say) of Asciidoc in general versus Markdown is that it aims to truly be a standard.

Markdown itself comes (not even implicitly, but explicitly!) with the philosophy that there is no "true" standard. It's very flexible, very customizable, and does not aim for interop between implementations, for tooling, and so on.

Asciidoc tries to focus on being a Standard with a capital "S" so that the entire ecosystem around it can interop properly without implementation specific quirks/incompatibilities.

Both are good tools but with completely different philosophies. I learned all of this because I wanted to make a fast markdown parser in WASM directly. And at the same time I wanted to have a common way to put together a book to be published. What I learned quickly when trying to come at Markdown from a technical perspective is that there are dozens or more Markdown flavors and the idea of "Markdown" as a "general thing" isn't accurate, there's not even really a "core" shared between the variants/flavors. Which is in stark contrast to Asciidoc.

edit: A small aside, I also learned that a few publishers that focus on tech writing specifically use Asciidoc for their "publishing" workflows. So in that realm Asciidoc is practically useful to know.

[subpixel]

Key word is "few", which is why AsciiDoc is so frustrating to work with. Not on account of it's own shortcoming, but because so little activity is going on in the community to push it forward or to drive further support.

For example, if GitHub fully supported AsciiDoc, you'd see a lot more people considering it. But it's just not worth the headache to them, apparently.

[ethanwillis]

I have to fully agree with you unfortunately :\

[teknopaul]

While it's true markdown isnt a standard. What ever your tool does defines it. For source code docs converted to HTML or man pages you only have one build.

Common mark is a standard if you need one.

[thayne]

> What ever your tool does defines it

What if you have multiple tools that use different flavors of markdown? Even if you don't ever use multiple tools on the same input, you have to remember which syntax is allowed by which tool.