2021年5月更新:推荐标记已弃用，取而代之的是神秘解析器(感谢astrojuanlu)

更新:现在sphinx文档正式支持并记录了这一点。

看起来它的基本实现已经进入了Sphinx，但还没有消息传出去。见github问题评论

安装的依赖关系:

pip install commonmark recommonmark

调整conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

这是对推荐方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1，所以

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

点击这里查看官方文件。

现在正式支持:http://www.sphinx-doc.org/en/stable/markdown.html

也见https://myst-parser.readthedocs.io/en/latest/syntax/optional.html的扩展，包括linkify使url自动链接。

做到这一点的“正确”方法是编写一个用于markdown的docutils解析器。(加上一个Sphinx选项来选择解析器。)这样做的好处是立即支持所有文档输出格式(但您可能并不关心这一点，因为大多数情况下已经存在类似的降价工具)。不需要从头开发解析器的方法:

You could cheat and write a "parser" that uses Pandoc to convert markdown to RST and pass that to the RST parser :-). You can use an existing markdown->XML parser and transform the result (using XSLT?) to the docutils schema. You could take some existing python markdown parser that lets you define a custom renderer and make it build docutils node tree. You could fork the existing RST reader, ripping out everything irrelevant to markdown and changing the different syntaxes (this comparison might help)... EDIT: I don't recommend this route unless you're prepared to heavily test it. Markdown already has too many subtly different dialects and this will likely result in yet-another-one...

更新:https://github.com/sgenoud/remarkdown是一个文档的markdown阅读器。它没有采用上述任何捷径，而是使用了受到PEG -markdown启发的Parsley PEG语法。

目前还不支持指令。

更新:https://github.com/readthedocs/recommonmark，是另一个文档阅读器，原生支持ReadTheDocs。派生自remarkdown，但使用CommonMark-py解析器。

它可以将特定的或多或少的自然Markdown语法转换为适当的结构，例如指向toctree的链接列表。*没有角色的通用本地语法。 支持嵌入任何rST内容，包括指令，使用' ' ' eval_rst fenced块以及指令DIRECTIVE_NAME:: ....的简写

更新:MyST是另一个文档/Sphinx阅读器。基于markdown-it-py，兼容CommonMark。

有一个通用的{ROLE_NAME} '…的语法。 有一个通用语法的指令' ' ' {DIRECTIVE_NAME}…fenced块。

在所有情况下，您都需要发明Markdown的扩展来表示Sphinx指令和角色。虽然你可能不需要全部，但有些像..Toctree::是必不可少的。 我认为这是最难的部分。在Sphinx扩展之前的reStructuredText已经比markdown丰富了。即使是大量扩展的markdown，比如pandoc的markdown，也主要是rST特性集的子集。那要去的地方可真多啊!

在实现方面，最简单的事情是添加一个泛型结构来表达任何docutils角色/指令。语法灵感的明显候选有:

属性语法，pandoc和其他一些实现已经在许多内联和块结构上允许这种语法。例如' foo '{。方法}-> ' foo ':方法:。 HTML / XML。从<span class="method">foo</span>到只插入doctils内部XML的最笨拙的方法! 某种用于指令的YAML ?

但是这种通用的映射并不是最简单的解决方案…… 目前讨论降价扩展最活跃的地方是https://groups.google.com/forum/#!主题/ pandoc-discuss, https://github.com/scholmd/scholmd/

这也意味着您不能只重用markdown解析器而不扩展它。通过支持自定义过滤器，Pandoc再次不负文档转换瑞士军刀的美誉。(事实上，如果我要接近这个问题，我会尝试在docutils阅读器/transformer /writer和pandoc阅读器/filters/writer之间建立一个通用的桥梁。这比你需要的要多，但回报会比狮身人面像/降价要大得多。)

另一个疯狂的想法:与其扩展markdown来处理Sphinx，不如扩展reStructuredText来支持(大部分)markdown的超集!美妙之处在于，你可以使用任何Sphinx的特性，同时还可以以低价编写大部分内容。

已经有相当多的语法重叠;最明显的是链接语法不兼容。我认为如果你添加对RST的支持，标记低链接，和###风格的标题，并将默认的“反撇号”角色更改为文字，并可能将缩进块更改为文字(RST支持>…对于报价现在)，你会得到一些可用的，支持大多数markdown。

请注意，使用maven和嵌入式Sphinx + MarkDown支持构建文档完全由以下maven插件支持:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

这里有一个新的选择。MyST为Markdown添加了一些功能，允许Sphinx像rst一样构建文档。 https://myst-parser.readthedocs.io/en/latest/