Markdown is an excellent choice for documentation
Good documentation isn't only about it being readable in plain-text. It is about being accurate, maintainable, easy to read (when processed) and even, dynamic (look at Stripe's documentation that contains your own API keys, not random ones). Anybody writing documentation with this goal in mind will quickly realize that Markdown is not fit for the job.<p>Asciidoc is fully compatible with markdown, and provides a lot more functionality out of the box.<p>Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this.<p>The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k.<p>A quick search on Google allowed me to find this page[0] which lists no less than 20 different markdown flavors.<p>Asciidoc comes in 1 and only 1 flavor that does most of everything you want.<p>Also, there's a great open-source project that allows you to create a documentation website in Aciidoc: <a href="https://antora.org/" rel="nofollow">https://antora.org/</a>. (I'm not affiliated, just a happy user)<p>[0]: <a href="https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f" rel="nofollow">https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684b...</a>