如何在Sphinx中实现从MD文件跳转的树形与子树结构展示

你需要在Sphinx中实现支持Markdown文件跳转的嵌套树形侧边栏导航，对应项目结构如下：

最终HTML渲染需达到的效果如下：

1. 安装必要依赖 #

• 首先安装Markdown解析扩展和支持树形导航的RTD主题，执行命令：
  pip install myst-parser sphinx-rtd-theme

2. 配置Sphinx的conf.py文件 #

在项目的conf.py中添加如下配置：

• 启用Markdown解析扩展：
  extensions = ['myst_parser']
• 识别MD和RST格式的源文件：
  source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}
• 设置HTML主题为RTD主题，该主题原生支持可折叠跳转的嵌套树形侧边栏：
  html_theme = 'sphinx_rtd_theme'

3. 配置toctree生成树形结构 #

toctree是Sphinx生成导航目录的核心配置，你可以在根目录的索引文件（index.rst或index.md）中添加配置，也可以在子目录中嵌套配置实现子树结构：

如果你用rst格式写根索引文件，配置如下：

.. toctree::
   :maxdepth: 4
   :caption: 项目导航
   :glob:

   首页.md
   一级目录1/*
   一级目录2/**

如果你用MyST语法的MD格式写根索引文件，配置如下：

```{toctree}
:maxdepth: 4
:caption: 项目导航
:glob:

首页.md
一级目录1/*
一级目录2/**

参数说明：

• maxdepth：控制树形目录的展开层级，数值越大支持的嵌套层级越深
• glob：开启通配符匹配，*匹配当前目录下所有文件，**递归匹配当前目录及所有子目录的文件
  如果需要实现子树结构，只需要在对应子目录中新建索引文件，在子目录的索引文件中再写一层toctree配置，根目录的toctree引用子目录的索引文件即可。

4. 编译验证 #

配置完成后执行编译命令生成HTML：
sphinx-build 你的文档目录 输出目录
打开输出目录中的HTML文件，即可看到侧边栏支持跳转、可折叠的嵌套树形导航，完全符合需求。

内容的提问来源于stack exchange，提问作者Snehasish Das