From d14e950881e7d4ecf3b2883d03b00713962b9ec2 Mon Sep 17 00:00:00 2001 From: Timotheus Kampik Date: Sat, 28 Jul 2018 18:02:32 +0200 Subject: [PATCH] #5216 update Markdown config doc to API changes --- doc/usage/markdown.rst | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst index f67b94cbd..413ae616c 100644 --- a/doc/usage/markdown.rst +++ b/doc/usage/markdown.rst @@ -22,26 +22,32 @@ Configuration To configure your Sphinx project for Markdown support, proceed as follows: -#. Install *recommonmark*:: +#. Install the Markdown parser *recommonmark*:: pip install recommonmark -#. Add the Markdown parser to the ``source_parsers`` configuration variable in - your Sphinx configuration file:: +#. Add *recommonmark* to the + :confval:`list of configured extensions `:: - source_parsers = { - '.md': 'recommonmark.parser.CommonMarkParser', + extensions = ['recommonmark'] + + .. versionchanged:: 1.8 + Version 1.8 deprecates and version 2.0 removes the ``source_parsers`` + configuration variable that was used by older *recommonmark* versions. + +#. 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 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 + standard *CommonMark* doesn't support. Read more in the `recommonmark documentation`__. __ https://recommonmark.readthedocs.io/en/latest/auto_structify.html