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 文档中阅读更多信息。