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* 添加到 list of configured extensions

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