Markdown is an excellent choice for documentation
Good documentation isn&#x27;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&#x27;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&#x27;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&#x27;s a great open-source project that allows you to create a documentation website in Aciidoc: <a href="https:&#x2F;&#x2F;antora.org&#x2F;" rel="nofollow">https:&#x2F;&#x2F;antora.org&#x2F;</a>. (I&#x27;m not affiliated, just a happy user)<p>[0]: <a href="https:&#x2F;&#x2F;gist.github.com&#x2F;vimtaai&#x2F;99f8c89e7d3d02a362117284684baa0f" rel="nofollow">https:&#x2F;&#x2F;gist.github.com&#x2F;vimtaai&#x2F;99f8c89e7d3d02a362117284684b...</a>