From e6693b5cae5083fdc7bc68304f6d0a01303e653e Mon Sep 17 00:00:00 2001
From: Timotheus Kampik <timotheus.kampik@signavio.com>
Date: Sun, 29 Jan 2017 10:58:22 +0100
Subject: [PATCH 1/2] document markdown support #2303 #825

---
 doc/config.rst   |  7 +++++--
 doc/contents.rst |  1 +
 doc/markdown.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 doc/markdown.rst

diff --git a/doc/config.rst b/doc/config.rst
index 5613d0bd6..c082dba2f 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -101,10 +101,13 @@ General configuration
    suffix that is not in the dictionary will be parsed with the default
    reStructuredText parser.
 
-
    For example::
 
-      source_parsers = {'.md': 'some.markdown.module.Parser'}
+      source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+
+   .. note::
+
+      Read more about how to use Markdown with Sphinx at :ref:`markdown`.
 
    .. versionadded:: 1.3
 
diff --git a/doc/contents.rst b/doc/contents.rst
index 0f5527bae..92fb13fcb 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -19,6 +19,7 @@ Sphinx documentation contents
    theming
    templating
    latex
+   markdown
    extensions
    extdev/index
    websupport
diff --git a/doc/markdown.rst b/doc/markdown.rst
new file mode 100644
index 000000000..04ae29466
--- /dev/null
+++ b/doc/markdown.rst
@@ -0,0 +1,44 @@
+.. highlightlang:: python
+
+.. _markdown:
+
+Markdown support
+================
+
+`Markdown <https://daringfireball.net/projects/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 `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__, a
+Python package for parsing the `CommonMark <http://commonmark.org/>`__ flavor. In addition, Sphinx uses
+`recommonmark <http://recommonmark.readthedocs.io/en/latest/index.html>`__, a Docutils bridge to CommonMark.
+
+
+Configuration
+-------------
+
+To configure your Sphinx project for markdown support, proceed as follows:
+
+#. Install CommonMark version **0.5.4** and recommonmark:
+
+   ::
+
+      pip install commonmark==0.5.4 recommonmark
+
+#. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file:
+
+   ::
+
+      source_parsers = {
+         '.md': 'recommonmark.parser.CommonMarkParser',
+      }
+
+   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 documentation <http://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.

From 98a39f8a51d3b544d6d9270e48d3deaa50178cda Mon Sep 17 00:00:00 2001
From: Timotheus Kampik <timotheus.kampik@signavio.com>
Date: Wed, 1 Feb 2017 19:16:05 +0100
Subject: [PATCH 2/2] document markdown support: work in review comments #2303
 #825

---
 doc/markdown.rst | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/doc/markdown.rst b/doc/markdown.rst
index 04ae29466..75a35b9d0 100644
--- a/doc/markdown.rst
+++ b/doc/markdown.rst
@@ -8,21 +8,22 @@ Markdown support
 `Markdown <https://daringfireball.net/projects/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 `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__, a
-Python package for parsing the `CommonMark <http://commonmark.org/>`__ flavor. In addition, Sphinx uses
-`recommonmark <http://recommonmark.readthedocs.io/en/latest/index.html>`__, a Docutils bridge to CommonMark.
+To support Markdown-based documentation, Sphinx can use
+`recommonmark <http://recommonmark.readthedocs.io/en/latest/index.html>`__.
+recommonmark is a Docutils bridge to `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__, a
+Python package for parsing the `CommonMark <http://commonmark.org/>`__ Markdown flavor.
 
 
 Configuration
 -------------
 
-To configure your Sphinx project for markdown support, proceed as follows:
+To configure your Sphinx project for Markdown support, proceed as follows:
 
-#. Install CommonMark version **0.5.4** and recommonmark:
+#. Install recommonmark:
 
    ::
 
-      pip install commonmark==0.5.4 recommonmark
+      pip install recommonmark
 
 #. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file: