Markdown — Sphinx documentation (2024)

Markdown is a lightweight markup language with a simplistic plain textformatting syntax. It exists in many syntactically different flavors. Tosupport Markdown-based documentation, Sphinx can use MyST-Parser.MyST-Parser is a Docutils bridge to markdown-it-py, a Python package forparsing the CommonMark Markdown flavor.

Configuration¶

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

Install the Markdown parser MyST-Parser:
```
pip install --upgrade myst-parser
```
See Also
How to Host Your Sphinx Documentation on GitHub Deploying a Sphinx project online — Sphinx documentation
Add myst_parser to thelist of configured extensions:
```
extensions = ['myst_parser']
```
Note
MyST-Parser requires Sphinx 2.1 or newer.
If you want to use Markdown files with extensions other than .md, adjustthe source_suffix variable. The following example configuresSphinx to parse all files with the extensions .md and .txt asMarkdown:
```
source_suffix = { '.rst': 'restructuredtext', '.txt': 'markdown', '.md': 'markdown',}
```
You can further configure MyST-Parser to allow custom syntax thatstandard CommonMark doesn’t support. Read more in the MyST-Parserdocumentation.