Sphinx多层toctree子页面重复标签问题及层级调整需求

问题分析 #

当前核心问题有两个：

• 重复标签警告：多个文件使用相同文件名a.md，Sphinx默认以文件名生成标签，导致标识冲突。
• 目录层级错误：二级页面的toctree未设置隐藏属性，Sphinx会将所有未隐藏的toctree条目纳入全局顶层目录，最终导致子页面与父页面同级展示。

解决方案 #

1. 消除重复标签警告 #

在每个文件开头添加唯一的自定义标签，覆盖默认的文件名标签：

• a/a.md开头添加：

  .. _a-a:
  

• a/a/a.md开头添加：

  .. _a-a-a:
  

2. 实现嵌套目录层级 #

调整两处toctree的配置，精准控制全局目录的层级展示：

修改index.md

设置:maxdepth: 2，让全局目录支持两级嵌套结构，同时引入父页面：

# namespace/project-name

## Table of Contents
```{toctree}
:maxdepth: 2

a/a

#### 修改`a/a.md`
添加页面标题，给子页面的`toctree`设置`:hidden:`（避免子页面被提升到全局顶层目录），同时保留子页面在当前页面的局部展示：
```markdown
.. _a-a:

# 一级A页面

## 子页面列表
```{toctree}
:hidden:
:maxdepth: 1

a/a

### 关键说明
之前设置`:maxdepth`无效，是因为二级页面的`toctree`未加`:hidden:`属性，Sphinx会自动将其中的所有条目提升到全局目录的顶层。添加`:hidden:`后，子页面的目录仅在父页面内展示，全局目录的层级完全由`index.md`中的`:maxdepth`参数控制。

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