diff options
| -rw-r--r-- | doc/usage/markdown.rst | 39 |
1 files changed, 27 insertions, 12 deletions
diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst index ed0cce013..7593ea6b0 100644 --- a/doc/usage/markdown.rst +++ b/doc/usage/markdown.rst @@ -22,26 +22,41 @@ Configuration To configure your Sphinx project for Markdown support, proceed as follows: -#. Install *recommonmark*:: +#. Install the Markdown parser *recommonmark* from its source on GitHub:: - pip install recommonmark + pip install git+https://github.com/rtfd/recommonmark -#. Add the Markdown parser to the ``source_parsers`` configuration variable in - your Sphinx configuration file:: + .. note:: - source_parsers = { - '.md': 'recommonmark.parser.CommonMarkParser', - } + The configuration as explained here requires recommonmark version + 0.5.0.dev or higher, which is at the time of writing not available on + PyPI. If you want to use a released recommonmark version, follow the + instructions in the `Sphinx 1.8 documentation`__. + +__ https://www.sphinx-doc.org/en/1.8/usage/markdown.html + +#. Add *recommonmark* to the + :confval:`list of configured extensions <extensions>`:: - You can replace ``.md`` with a filename extension of your choice. + extensions = ['recommonmark'] -#. Add the Markdown filename extension to the ``source_suffix`` configuration - variable:: + .. versionchanged:: 1.8 + Version 1.8 deprecates and version 3.0 removes the ``source_parsers`` + configuration variable that was used by older *recommonmark* versions. - source_suffix = ['.rst', '.md'] +#. If you want to use Markdown files with extensions other than ``.md``, adjust + the :confval:`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', + } #. You can further configure *recommonmark* to allow custom syntax that - standard *CommonMark* doesn't support. Read more in the `recommonmark + standard *CommonMark* doesn't support. Read more in the `recommonmark documentation`__. __ https://recommonmark.readthedocs.io/en/latest/auto_structify.html |