python - 使用带有 Markdown 的 Sphinx 而不是 reST

Question

我讨厌 reST，但喜欢 Sphinx。有没有办法让 Sphinx 读取 Markdown 而不是 reStructuredText？

Answer 1

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

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

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

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

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

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

MyST 解析器需要 Sphinx 2.1 或更高版本。对于早期版本的 Sphinx，您可以使用 recommonmark 在 Sphinx 中使用 Markdown .结帐earlier revisions找出答案。