这是对推荐方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1，所以

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

点击这里查看官方文件。

做到这一点的“正确”方法是编写一个用于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>

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

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

有解决方法 sphinx-quickstart.py脚本生成一个Makefile。 每次您想要生成文档以将Markdown转换为reStructuredText时，都可以轻松地从Makefile调用Pandoc。

我采纳了Beni的建议，使用pandoc来完成这项任务。安装后，下面的脚本将把源目录中的所有markdown文件转换为rst文件，这样您就可以用markdown编写所有文档。希望这对其他人有用。

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))