Sphinx支持Markdown吗

是的,Sphinx 支持 Markdown，从 Sphinx 1.5 版本开始，可以通过安装扩展来支持 Markdown 格式的文档编写。

1. 推荐使用 myst-parser 扩展：

   • 这是目前最流行、功能最完善的 Sphinx Markdown 解析器（取代了旧的 recommonmark 扩展，后者已停止维护）。
   • 安装命令：pip install myst-parser
   • 在 conf.py 中配置：

     extensions = [
         # ... 其他扩展
         'myst_parser',
     ]

   • 然后在 conf.py 中添加源文件后缀（如果还不支持）：

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

2. 支持的功能：

   • 标准的 Markdown 语法（标题、列表、表格、代码块、链接、图片等）。
   • 通过 MyST 语法（Markedly Structured Text，即标记性结构化文本的语法格式，一种在 Markdown 中集成 reStructuredText 功能的方式）支持 Sphinx 特有的指令（如 .. note::、.. warning::、.. code-block:: 等）。

     :::{note}
     这是一个在 Markdown 文件中的 Sphinx 笔记。
     :::

   • 支持表格渲染、数学公式（通过 LaTeX）、交叉引用（{ref}、{doc} 等）。

3. 注意点：

   • Sphinx 的原生格式是 reStructuredText (.rst)，Markdown 是通过外部扩展实现的，因此功能上可能稍微有所不同（某些复杂的 Sphinx 指令可以在 Markdown 中直接使用 MyST 语法，但并不是 100% 兼容所有 rst 特性）。
   • 建议：新项目用 .rst 或 .md 都可以，但 Mix 使用会导致混乱，选择一种主要格式（大部分人选择 .rst 因为与 Sphinx 原生生态完全一致，或选择 .md 因为更多人熟悉）。myst-parser 是目前最稳定的方案。

推荐使用 myst-parser 扩展让 Sphinx 完美支持 Markdown（同时支持 MyST 语法以实现高级功能）。