使用Furo主题时Sphinx toctree条目数学表达式无法渲染

问题描述 #

使用Sphinx搭配Furo主题编写文档时，index.rst的toctree列表项中直接使用:math:角色无法被正确解析，示例代码如下：

第一种写法：

.. toctree::
   :maxdepth: 4
  
   Bounds for :math:`|\zeta(s)|` <Art06.rst>
   Size of :math:`L(1,\chi)` <Art07.rst>

第二种写法（仅指定文件名，依赖目标文件标题）：

.. toctree::
   :maxdepth: 4
  
   Art06.rst
   Size of :math:`L(1,\chi)` <Art07.rst>

其中Art06.rst的标题为：

Bounds for :math:`|\zeta(s)|`
=============================

以上两种方式均无法正常渲染:math:角色。

核心原因 #

toctree的列表项文本默认被当作纯文本处理，不会解析reStructuredText的角色语法（包括:math:），因此直接写入的公式会原样显示而非渲染。

解决步骤 #

1. 定义文本替换标签 #

在index.rst的toctree代码块之前，添加reStructuredText的替换定义，将包含公式的标题封装为标签：

.. |zeta-bound-title| replace:: Bounds for :math:`|\zeta(s)|`
.. |L-function-title| replace:: Size of :math:`L(1,\chi)`

2. 在toctree中使用替换标签 #

修改toctree代码，用替换标签替代原有的文本内容：

.. toctree::
   :maxdepth: 4
  
   |zeta-bound-title| <Art06.rst>
   |L-function-title| <Art07.rst>

3. 确认MathJax扩展已启用 #

打开项目的conf.py配置文件，确保extensions列表中包含sphinx.ext.mathjax：

extensions = [
    # 其他已启用的扩展...
    'sphinx.ext.mathjax',
]

若需要使用MathJax 3版本（推荐），可额外添加路径配置：

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

4. 重新构建文档 #

执行Sphinx的构建命令，重新生成HTML文档：

make html

完成以上步骤后，toctree中的数学公式即可正常渲染。

内容的提问来源于stack exchange，提问作者Olivier Ramaré