sphinx/doc/usage/markdown.rst

.. highlight:: python

========
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:

#. Install recommonmark::

      pip install recommonmark

#. Add the Markdown parser to the ``source_parsers`` configuration variable in
   your Sphinx configuration file::

      source_parsers = {
         '.md': 'recommonmark.parser.CommonMarkParser',
      }

   You can replace `.md` with a filename extension of your choice.

#. Add the Markdown filename extension to the  ``source_suffix`` configuration
   variable::

      source_suffix = ['.rst', '.md']

#. You can further configure recommonmark to allow custom syntax that standard
   CommonMark doesn't support. Read more in the `recommonmark documentation
   <shttp://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.

.. _Markdown: https://daringfireball.net/projects/markdown/
.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html
.. _CommonMark-py: <https://github.com/rtfd/CommonMark-py>
.. _CommonMark: http://commonmark.org/