Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

I've done a lot of research and testing with Markdown, Asciidoc, and reStructuredText to see which would work best for my company's documentation needs. We ended up going with Asciidoc and Antora for the following reasons.

Asciidoc:

* Almost as simple as Markdown.

* Less convoluted than reStructuredText.

* Excellent support for complex tables, captions, callouts, etc.

* We prefer Asciidocs table structure to Markdown's since it is easier to create and maintain.

* Excellent documentation.

Antora:

* Comes with a default template, which makes building prototypes easier.

* Ability to pull from multiple git repositories.

* Native Asciidoc support.

* Fast compile times.

* Good documentation.

Based on our research, I even migrated my personal 11ty sites from Markdown to Asciidoc and have been quite happy with it.

I'm primarily a Python dev. I *hate* RST. I despise that it's really the only viable choice for docstrings in Python and wish for something rustdoc-like to be ported to Python

Last year we changed the source format for MDN from some extremely messy, WYSIWYG-authored HTML to something that would be easier for authors to use. We considered Asciidoc and reST, and despite its limitations, we chose Markdown (GFM specifically) for two reasons:

1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.

2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.

One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.

If you're interested, we blogged about this project: https://openwebdocs.org/content/posts/markdown-conversion/.

Same.

Good news though, the jupyter devs created myst (https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h...), a superset of markdown that has almost all the features of rst, and can embed rst when it falls short.

And there is a plugin to use it with sphinx. It can even reside in a project that started with rst files, both format can coexist.

With this and sphinx-autoreload, writing doc is so much better.

You made the right choice, rst is not user friendly, even for tech savvy people.

I'll take the opportunity to do a shameless plug for the amazing "Markedly Structured Text", or MyST, a markdown flavor that is both easy to write like markdown, and expressive like rst.

Basically, if you know markdown, you can write decent MyST already. In fact, any markdown is valid MyST and .md is a valid file extension for MyST.

Once you want more, the syntax offers richer construct, but still easy enough to use.

Check it out: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h...

I wanted to love asciidoc because the format rocks, but it never took off and the tooling is still lacking. MyST piggy back on markdown ecosystem, this is less of a problem.

Also, the devs behind it also have a very good track record at creating a good FOSS ecosystem.