您可以在同一个Sphinx项目中使用Markdown和reStructuredText。 如何做到这一点在Sphinx文档中有简要的说明。

安装myst-parser (pip Install myst-parser)然后编辑conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

source_suffix = ['.rst', '.md']

我在Github上创建了一个小的示例项目(serra/sphinx with-markdown)，演示它是如何工作的。它使用Sphinx 3.5.4版本和myst-parser 0.14.0版本。

事实上，MyST解析器允许您用Markdown编写整个Sphinx文档。它支持指令，并有几个扩展，你可以通过conf.py中的配置来启用。

MyST解析器要求Sphinx 2.1或更高版本。对于Sphinx的早期版本，可以使用推荐标记在Sphinx中使用Markdown。查看这个答案的早期版本来找出答案。

我采纳了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(' '))

您可以在同一个Sphinx项目中使用Markdown和reStructuredText。 如何做到这一点在Sphinx文档中有简要的说明。

安装myst-parser (pip Install myst-parser)然后编辑conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

source_suffix = ['.rst', '.md']

我在Github上创建了一个小的示例项目(serra/sphinx with-markdown)，演示它是如何工作的。它使用Sphinx 3.5.4版本和myst-parser 0.14.0版本。

事实上，MyST解析器允许您用Markdown编写整个Sphinx文档。它支持指令，并有几个扩展，你可以通过conf.py中的配置来启用。

MyST解析器要求Sphinx 2.1或更高版本。对于Sphinx的早期版本，可以使用推荐标记在Sphinx中使用Markdown。查看这个答案的早期版本来找出答案。

这没有使用Sphinx，但是MkDocs将使用Markdown构建您的文档。我也讨厌rst，到目前为止我真的很喜欢MkDocs。

Markdown和ReST做不同的事情。

RST为处理文档提供了一个对象模型。

Markdown提供了一种雕刻文本的方法。

从您的sphinx项目中引用Markdown内容，使用RST来stub出一个较大文档的整体信息架构和流程，这似乎是合理的。让markdown发挥它的作用，让作者专注于写作文本。

是否有一种方法来引用markdown域，只是按原样雕刻内容?RST/sphinx似乎已经解决了像toctree这样的特性，而没有在markdown中复制它们。

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