Markdown

Markdown 是一种轻量级标记语言，具有简单的纯文本格式语法。它存在着许多在句法上不同的 风格 。要支持基于 Markdown 的文档，Sphinx 可以使用 MyST-Parser 。MyST-Parser 是连接 Docutils 和 markdown-it-py 的桥梁，是一个用于解析 CommonMark 风格的 Markdown 的 Python 包。

配置

要为您的 Sphinx 项目配置 Markdown 支持，请按照以下步骤进行：

1. 安装 Markdown 解析器 MyST-Parser:

   pip install --upgrade myst-parser
   

2. 把 myst_parser 添加到列表 已配置的扩展 中:

   extensions = ['myst_parser']
   

   备注

   MyST-Parser 要求 Sphinx 2.1 或更高。

3. 如果要使用不以“.md”为扩展名的 Markdown 文件，请调整 source_suffix 变量。下面的示例将配置 Sphinx 把所有扩展名为“.md”和“.txt”的文件解析为 Markdown：

   source_suffix = {
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
   }
   

4. 你还可以进一步配置 MyST-Parser 使其支持标准 CommonMark 原本不支持的自定义语法。更多详细信息请阅读 MyST-Parser 文档 。