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

    pip install --upgrade recommonmark
    

    Nota

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

  2. Add recommonmark to the list of configured extensions:

    extensions = ['recommonmark']
    

    Distinto en la versión 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 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.