Markdown

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

配置

要配置Sphinx项目以获得Markdown支持，请执行以下操作:

1. 安装Markdown解析器 recommonmark:

   pip install --upgrade recommonmark
   

   注解

   此处说明的配置需要6.5.0或更高版本的propmonmark。

2. 将 recommonmark 添加到 已配置的扩展名列表

   extensions = ['recommonmark']
   

   在 1.8 版更改: 版本1.8弃用，版本3.0删除了旧的 recommonmark 版本使用的 source_parsers 配置变量。

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

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

4. 您可以进一步配置 recommonmark 以允许标准 CommonMark 不支持的自定义语法。 阅读 recommonmark documentation 中的更多内容。