Sphinx升级后自动注入含colon类的span，如何禁用该行为？

1. 修改自定义角色的渲染逻辑 #

如果:header:是项目中自定义的rst角色（通常在conf.py或自定义扩展中定义），可以直接调整角色的实现代码，避免输出额外的colon类span。

比如原来的角色定义可能保留了包含冒号的原始标记文本，修改为直接生成干净的标题节点：

from docutils import nodes
from docutils.parsers.rst import roles

def header_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    # 直接用纯文本创建标题节点，不传递带冒号的rawtext
    rubric_node = nodes.rubric(text, text)
    return [rubric_node], []

# 注册自定义角色
roles.register_local_role('header', header_role)

2. 替换为原生rst小标题语法 #

如果:header:仅用于生成小标题，完全可以用rst原生语法替代，彻底避免Sphinx的自动colon注入：

• 使用rubric指令：

.. rubric:: 你的小标题文本

• 或者用下划线式标题（根据层级选择对应符号）：

你的小标题文本
^^^^^^^^^^^^^^^^

3. 排查第三方扩展影响 #

如果是某个第三方扩展导致的colon span注入，检查conf.py中的extensions列表，暂时禁用可疑扩展测试，确认后查看扩展文档是否有相关配置项可以关闭该行为。

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