Markdown support

Markdown is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different flavors. To support Markdown-based documentation, Sphinx can use recommonmark. recommonmark is a Docutils bridge to CommonMark-py, a Python package for parsing the CommonMark Markdown flavor.


To configure your Sphinx project for Markdown support, proceed as follows:

  1. Install recommonmark:

    pip install recommonmark
  2. Add the Markdown parser to the source_parsers configuration variable in your Sphinx configuration file:

    source_parsers = {
       '.md': 'recommonmark.parser.CommonMarkParser',

    You can replace .md with a filename extension of your choice.

  3. Add the Markdown filename extension to the source_suffix configuration variable:

    source_suffix = ['.rst', '.md']
  4. You can further configure recommonmark to allow custom syntax that standard CommonMark doesn’t support. Read more in the recommonmark documentation.