mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
parent
0aa6ff3681
commit
e6693b5cae
@ -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
|
||||
|
||||
|
@ -19,6 +19,7 @@ Sphinx documentation contents
|
||||
theming
|
||||
templating
|
||||
latex
|
||||
markdown
|
||||
extensions
|
||||
extdev/index
|
||||
websupport
|
||||
|
44
doc/markdown.rst
Normal file
44
doc/markdown.rst
Normal file
@ -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>`__.
|
Loading…
Reference in New Issue
Block a user