使用Markdown的Sphinx而不是reST

我推荐使用MyST Markdown。这是Markdown的一种风格，旨在引入reStructuredText的主要特性。MyST代表显著结构化文本，可以被认为是“带有Markdown的rST”。

MyST是CommonMark标准的超集，它被定义为通过markdown-it-py包对CommonMark进行的离散扩展的集合)。这意味着CommonMark语法可以与MyST一起开箱即用，但是如果您愿意，您也可以使用更多的语法特性。

MyST为reStructuredText中的几乎每个特性都提供了语法，并且针对完整的Sphinx测试套件进行了测试，以确保可以重新创建相同的功能。例如:

下面是如何在MyST中编写指令:

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

这是你在《神秘岛》中如何编写角色的方法

Here's some text and a {rolename}`role content`

MyST Markdown的Sphinx解析器也有一些很好的Sphinx特有的特性，比如使用Markdown链接语法([some text](someelink))来处理Sphinx中的交叉引用。例如，你可以在MyST中定义一个标签，并引用它，像这样:

(my-label)=
# My header

Some text and a [cross reference](my-label).

对于一个更完整的MyST Markdown语法列表，一个很好的参考是Jupyter Book备考表，它有许多常见的文档需求和各自的MyST语法来完成它。(MyST是作为Jupyter Book的一个组件创建的，尽管从技术角度来看它是一个完全独立的项目)。

在Sphinx文档和ReadTheDocs文档中，MyST现在是Sphinx推荐的Markdown工具。

要将MyST解析器添加到Sphinx文档中，只需执行以下操作:

pip install myst-parser

在conf.py中添加:

extensions = [
  ...
  "myst_parser",
  ...
]

您的Sphinx文档现在将能够解析CommonMark markdown以及扩展的MyST markdown语法!请查看MyST文档以获取更多信息!

我希望这有助于澄清一些事情!

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

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

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/

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