Sphinx侧边栏导航如何仅显示.rst文件标题？

我之前折腾这个主题的时候也碰到过类似的导航显示问题，结合你的文档结构和需求，咱们一步步来调整：

问题根源 #

sphinx_press_theme的侧边栏导航逻辑和Sphinx默认主题差异挺大的——默认主题会按toctree的层级展示页面+页面内子标题，而这个主题默认可能会优先渲染页面内的子标题，反而漏了嵌套目录下的独立页面标题（比如你的About页面）。

具体解决方案 #

1. 调整toctree的核心配置 #

首先修改index.rst里的toctree，确保直接列出所有需要在侧边栏显示的.rst文件，并把maxdepth设为1（这样只会抓取每个页面的主标题，不会拉取页面内的子标题）：

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   introduction/introduction
   introduction/about/about

⚠️ 注意：如果你的introduction/introduction.rst里还嵌套了指向about页面的toctree，一定要删掉它——否则主题会把About当成Introduction的子项，而不是独立的侧边栏条目。

2. 配置主题的侧边栏深度 #

在conf.py里添加html_theme_options，强制主题只展示一级导航（也就是页面主标题），不渲染页面内的子标题：

html_theme = "sphinx_press_theme"
html_theme_options = {
    "sidebar_depth": 1,
}

3. 确保页面主标题格式正确 #

每个.rst文件的主标题必须用一级标题格式（标题文本下方用等号下划线），这样Sphinx才会把它识别为页面的顶级标题，进而在导航中显示：
比如introduction/about/about.rst的开头应该是：

About
=====

这里是About页面的内容...

4. 重新构建文档 #

执行构建命令更新静态文件：

make html

这样调整后，侧边栏应该就只会显示你想要的Contents: Introduction About这几个页面标题了。

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