如何在sphinx-build生成的index.html仅显示文档标题

开发者阿泽

2026-5-28

解决Sphinx索引页显示副标题的问题

首先得明确：Sphinx的索引页（对应toctree生成的目录）默认会抓取文档里的一级标题——哪怕你把文字改成副标题的表述，只要它还是用等长下划线标记的一级标题格式，toctree依然会把它列出来。

要解决这个问题，有几个实用的办法：

用.. rubric::指令替代标题格式：rubric会渲染成类似标题的样式，但不会被toctree识别为可索引的标题，完美适配副标题需求：
```
============== Document Title ==============
.. rubric:: Section Title (Document Subtitle)
```
调整toctree的maxdepth参数：打开你的index.rst找到toctree块，把maxdepth设置为1，这样目录只会显示每个文档的主标题，不会深入抓取文档内的下级标题：
```
.. toctree::
   :maxdepth: 1
   :caption: 文档目录

   your_target_document
```
给副标题添加:hidden:标记：如果坚持要用标题格式，可以给副标题加上隐藏属性，让Sphinx不把它加入索引目录：
```
============== Document Title ==============
Section Title (Document Subtitle)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:hidden:
```
这个方法需要确保你的Sphinx版本支持该属性，主流新版本都没问题。