summaryrefslogtreecommitdiffstats
path: root/doc/usage/markdown.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/usage/markdown.rst52
1 files changed, 52 insertions, 0 deletions
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>`::
+
+ 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