Markdown

Markdown is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different flavors. To support Markdown-based documentation, Sphinx can use MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.

配置

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

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

    pip install --upgrade myst-parser

  2. 将 myst_parser 添加到 :confval :已配置扩展列表 <extensions>

    extensions = ['myst_parser']

    备注

    MyST-Parser 需要 Sphinx 2.1 或更高版本.

  3. 如果您想使用扩展名不是 .md 的 Markdown 文件,请调整 :confval :source_suffix 变量.以下示例配置 Sphinx 以将所有扩展名为 .md 和 .txt 的文件解析为 Markdown:

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

  4. 您可以进一步配置 MyST-Parser 以允许标准 CommonMark 不支持的自定义语法.有关更多信息,请阅读 MyST-Parser 文档.