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