Markdown

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

配置

要为 Markdown 支持配置您的 Sphinx 项目，请按以下步骤操作

  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 文档了解更多信息。