Markdown

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.

Configuration

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.