python - Using Sphinx with Markdown instead of reST

Question

I hate reST but love Sphinx. Is there a way that Sphinx reads Markdown instead of reStructuredText?

Answer 1

You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented in the Sphinx documentation.

Install myst-parser (pip install myst-parser) and then edit conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

source_suffix = ['.rst', '.md']

I've created a small example project on Github (serra/sphinx-with-markdown) demonstrating how (and that) it works. It uses Sphinx version 3.5.4 and myst-parser version 0.14.0.

In fact, MyST parser allows you to write your entire Sphinx documentation in Markdown. It supports directives and has several extensions you can enable through configuration in conf.py.

MyST parser requires Sphinx 2.1 or later. For earlier versions of Sphinx, you could use Markdown in Sphinx using recommonmark. Checkout earlier revisions of this answer to find out how.