Sphinx

# 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 MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.

## Configuration

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

1. Install the Markdown parser MyST-Parser:

       pip install --upgrade myst-parser

2. Add myst_parser to the `list of configured extensions`:

       extensions = ['myst_parser']

   Note

   MyST-Parser requires Sphinx 2.1 or newer.

3. If you want to use Markdown files with extensions other than `.md`, adjust the `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 MyST-Parser to allow custom syntax that standard CommonMark doesn’t support. Read more in the MyST-Parser documentation.