Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Recommend MyST-Parser for Markdown usage #9112

Merged
merged 1 commit into from
Apr 18, 2021
Merged

Recommend MyST-Parser for Markdown usage #9112

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 13 additions & 19 deletions doc/usage/markdown.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,37 +8,31 @@ 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
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.

__ https://daringfireball.net/projects/markdown/
__ https://recommonmark.readthedocs.io/en/latest/index.html
__ https://github.com/rtfd/CommonMark-py
__ https://myst-parser.readthedocs.io/en/latest/
__ https://github.com/executablebooks/markdown-it-py
__ https://commonmark.org/

Configuration
-------------

To configure your Sphinx project for Markdown support, proceed as follows:

#. Install the Markdown parser *recommonmark*::
#. Install the Markdown parser *MyST-Parser*::

pip install --upgrade recommonmark
pip install --upgrade myst-parser

.. note::

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

#. Add *recommonmark* to the
#. Add *myst_parser* to the
:confval:`list of configured extensions <extensions>`::

extensions = ['recommonmark']
extensions = ['myst_parser']

.. versionchanged:: 1.8
Version 1.8 deprecates and version 3.0 removes the ``source_parsers``
configuration variable that was used by older *recommonmark* versions.
.. note::
MyST-Parser requires Sphinx 2.1 or newer.

#. If you want to use Markdown files with extensions other than ``.md``, adjust
the :confval:`source_suffix` variable. The following example configures
Expand All @@ -51,8 +45,8 @@ To configure your Sphinx project for Markdown support, proceed as follows:
'.md': 'markdown',
}

#. You can further configure *recommonmark* to allow custom syntax that
standard *CommonMark* doesn't support. Read more in the `recommonmark
#. You can further configure *MyST-Parser* to allow custom syntax that
standard *CommonMark* doesn't support. Read more in the `MyST-Parser
documentation`__.

__ https://recommonmark.readthedocs.io/en/latest/auto_structify.html
__ https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html