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.
