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

   Note:

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

2. Add *recommonmark* to the "list of configured extensions":

      extensions = ['recommonmark']

   Changed in version 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.
