Sphinx toctree侧边栏注释文本无法应用样式的解决咨询

核心思路 #

Sphinx默认会把toctree条目内的文本当作纯文本解析，直接写入**加粗**或*斜体*这类RST标记会被原样输出。要实现带样式的自定义文本，可通过**RST替换（Substitution）**间接实现，全程无需修改子级.rst文件。

具体步骤 #

1. 在顶层index.rst开头定义带样式的替换变量
   用.. |替换名| replace::语法预先定义带样式的文本，示例：

   .. |核心功能模块| replace:: **核心功能模块**
   .. |快速入门指南| replace:: *快速入门指南*
   

   这里的**和*是标准RST的加粗、斜体标记，会被Sphinx正常解析。

2. 在toctree中引用替换变量
   在toctree条目里，用|替换名| <文件名>的格式关联自定义文本与对应子文档，示例：

   .. toctree::
       :maxdepth: 2
       :caption: 文档目录
   
       |核心功能模块| <core_module>
       |快速入门指南| <quickstart>
   

3. 验证渲染效果
   重新构建文档（执行命令sphinx-build -b html docs/source docs/build），侧边栏目录项就会显示带加粗/斜体的自定义文本，而非原样输出标记。

额外说明 #

• 该方法完全符合Sphinx的RST语法规范，ReadTheDocs主题可完美适配渲染结果。
• 若需全局复用这些带样式文本，也可将替换定义放到conf.py的rst_prolog配置项中，无需在每个文档重复定义。

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