Sphinx侧边菜单未显示全部页面问题求助

安全阿岳

2026-8-3

解决Sphinx侧边菜单仅显示部分页面的问题

排查与修复方案

检查conf.py中的exclude_patterns配置：
确认未显示的4个页面是否被加入了排除列表，比如exclude_patterns = ['_build', 'docs/unused/*']这类规则会直接屏蔽对应文件/目录。只需将目标页面从该列表中移除即可。
核对未显示页面的文件名：
Sphinx默认会忽略下划线开头的.rst文件（如_internal_guide.rst）。如果你的页面是这类命名，要么修改文件名去掉开头下划线，要么在toctree中手动明确列出：
```
.. toctree::
   :glob:
   :titlesonly:
   
   *
   _internal_guide
   _hidden_settings
```
确认未显示页面包含一级标题：
你的toctree启用了:titlesonly:参数，该参数要求被收录的页面必须有一级标题（如用=====或#定义的标题）。若页面缺失一级标题，Sphinx不会将其纳入侧边菜单，补充标题即可：
```
# 示例页面标题
页面正文内容...
```
检查手动添加页面的格式：
手动添加时要保证每个文件名单独一行，且与*保持相同缩进（通常为3-4个空格），格式示例：
```
.. toctree::
   :glob:
   :titlesonly:
   
   *
   missing_page1
   missing_page2
   missing_page3
   missing_page4
```
清理缓存后重新构建：
残留的构建缓存可能导致页面不更新，先删除_build目录，再重新执行sphinx-build命令完成全量构建。