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 the Markdown parser recommonmark:

   pip install --upgrade recommonmark

   Note

   The configuration as explained here requires recommonmark version 0.5.0 or later.

2. Add recommonmark to the :confval:`list of configured extensions <extensions>`:

   extensions = ['recommonmark']

   .. versionchanged:: 1.8
      Version 1.8 deprecates and version 3.0 removes the ``source_parsers``
      configuration variable that was used by older *recommonmark* versions.

3. If you want to use Markdown files with extensions other than .md, adjust the :confval:`source_suffix` variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

   source_suffix = {
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
   }

4. You can further configure recommonmark to allow custom syntax that standard CommonMark doesn't support. Read more in the recommonmark documentation.