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

我推荐使用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文档以获取更多信息!

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

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

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

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

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

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