doc: Rework "markdown" document

There are a number of cleanup items.

- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/config.rst

@@ -136,7 +136,7 @@ General configuration
 
    .. note::
 
-      Read more about how to use Markdown with Sphinx at :ref:`markdown`.
+      Read more about how to use Markdown with Sphinx at :doc:`/markdown`.
 
    .. versionadded:: 1.3
 

doc/markdown.rst

@@ -1,33 +1,26 @@
 .. highlight:: 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
-`recommonmark <https://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.
+========
+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
+parsing the `CommonMark`_ Markdown flavor.
 
 Configuration
 -------------
 
 To configure your Sphinx project for Markdown support, proceed as follows:
 
-#. Install recommonmark:
-
-   ::
+#. Install recommonmark::
 
       pip install recommonmark
 
-#. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file:
-
-   ::
+#. Add the Markdown parser to the ``source_parsers`` configuration variable in
+   your Sphinx configuration file::
 
       source_parsers = {
          '.md': 'recommonmark.parser.CommonMarkParser',
@@ -35,11 +28,16 @@ To configure your Sphinx project for Markdown support, proceed as follows:
 
    You can replace `.md` with a filename extension of your choice.
 
-#. Add the Markdown filename extension to the  ``source_suffix`` configuration variable:
-
-   ::
+#. 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 <https://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.
+#. You can further configure recommonmark to allow custom syntax that standard
+   CommonMark doesn't support. Read more in the `recommonmark documentation
+   <shttp://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.
+
+.. _Markdown: https://daringfireball.net/projects/markdown/
+.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html
+.. _CommonMark-py: <https://github.com/rtfd/CommonMark-py>
+.. _CommonMark: http://commonmark.org/