From cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 19:25:40 +0200 Subject: Adding upstream version 7.2.6. Signed-off-by: Daniel Baumann --- doc/usage/markdown.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 doc/usage/markdown.rst (limited to 'doc/usage/markdown.rst') diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst new file mode 100644 index 0000000..ac24f8d --- /dev/null +++ b/doc/usage/markdown.rst @@ -0,0 +1,52 @@ +.. highlight:: python + +.. _markdown: + +======== +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. + +__ https://daringfireball.net/projects/markdown/ +__ 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 *MyST-Parser*:: + + pip install --upgrade myst-parser + +#. Add *myst_parser* to the + :confval:`list of configured extensions `:: + + extensions = ['myst_parser'] + + .. 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 + 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 *MyST-Parser* to allow custom syntax that + standard *CommonMark* doesn't support. Read more in the `MyST-Parser + documentation`__. + +__ https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html -- cgit v1.2.3