Sphinx supports Markdown alongside reStructuredText now

The New Docs are being built with Sphinx and written in reStructuredText. Just today, our friends at Read the Docs shipped a Sphinx extension that allows Markdown (the Commonmark flavour) in Sphinx project. You don’t have to choose; different pages can be written in either markup language.

They point out that Markdown still isn’t a first-class markup language:

We think that Sphinx’s power to reference code and other programming concepts is quite powerful. However, all content doesn’t need this ability. When you’re writing content that just needs to have basic text formatting and links, Commonmark is a great option for this.

We imagine that API reference documentation will continue to be authored in RST for quite some time. Also index pages and other reference heavy content will continune to be RST. FAQ’s, blog posts, and other less reference heavy content is a great candidate for writing in Commonmark.

I’m going to advocate that we primarily use reStructuredText in the new docs. However for pages that don’t need complex formatting, Markdown may be a perfectly fine choice to start with. Once the document becomes complex it’s trivial to migrate any individual page to reST via pandoc.