Sphinx文档中如何实现跨层级标题布局并隐藏过渡标题？
2026-8-10
可以通过添加隐藏的过渡标题实现这个层级需求，具体操作如下：
Sphinx 依赖 reStructuredText 的标题规则：同一种下划线符号的首次出现顺序决定其对应层级。要让「Section」类标题（短划线 -）对应 h2，就得先让短划线标题在 h2 层级上「注册」，再用其他符号对应 h3 层级的「Article」。
直接上可运行的 reStructuredText 代码：
========== Title ========== .. rubric:: Section 0 :hidden: ------------------- Section 0 ------------------- Article 1 ~~~~~~~~~ ------------------- Section 1 ------------------- Article 2 ~~~~~~~~~
原理说明：
- 用
:hidden:标记隐藏了「Section 0」标题，它不会在最终文档中显示，但会被 Sphinx 解析。 - 短划线
-首次出现在这个隐藏标题上，被 Sphinx 判定为 h2 层级（仅次于最高级的=）。 - 波浪线
~作为后出现的下划线符号，自动对应 h3 层级，用来标记「Article」类标题。 - 后续的「Section 1」用短划线，自然就会渲染为 h2，而「Article 1/2」用波浪线渲染为 h3，完全符合你要的布局。
内容的提问来源于stack exchange，提问作者Gouvernathor
相关产品推荐
相关产品推荐
