Sphinx（Jinja）中如何为标题创建自定义ID？

你遇到的问题其实是因为用.. _my-custom-id:的方式是创建了交叉引用标签，而非直接替换标题的原生ID，所以Sphinx会同时保留自动生成的s-id{数字}/id{数字}和你定义的引用ID。要完全自定义标题的ID，你可以用下面两种方案：

方法一：直接用:name:属性指定标题ID #

这是针对单个标题设置自定义ID最直接的方式，在标题下方添加:name:属性即可：

مثال سرتیتر
============
:name: my-custom-id

转换为HTML后，标题的ID会直接变成你指定的my-custom-id，不会再生成默认的s-id1或id1，最终HTML代码大概是这样：

<h1 id="my-custom-id">مثال سرتیتر<a class="headerlink" href="#my-custom-id" title="Permalink to this headline">¶</a></h1>

注意：:name:要紧跟在标题的下方，不需要额外缩进，只要保持在标题的同一内容区块里就行。

方法二：配置扩展实现批量友好ID（可选） #

如果你有大量非英文标题，想要自动生成更友好的ID（而非手动逐个设置），可以启用sphinx.ext.autosectionlabel扩展，并自定义slug规则：

1. 在你的Sphinx项目的conf.py中添加这个扩展：

   extensions = [
       # 保留你已有的其他扩展
       'sphinx.ext.autosectionlabel',
   ]
   
   # 可选：为自动标签添加文档前缀，避免不同文档间的ID冲突
   autosectionlabel_prefix_document = True
   

2. 如果默认的slug生成规则（非英文时生成s-id{数字}）不符合需求，你还可以自定义slugify函数。在conf.py中添加：

   from sphinx.util import slugify
   
   def my_custom_slugify(value):
       # 这里可以根据你的需求自定义处理逻辑，比如把非英文转成拼音、英文缩写等
       # 示例：假设是波斯语，你可以用transliterate库转成拉丁字母
       # import transliterate
       # return transliterate.translit(value, 'fa', reversed=True)
       return slugify(value)  # 或者替换成你的自定义逻辑
   
   # 替换默认的slugify函数
   sphinx.util.slugify = my_custom_slugify
   

这样配置后，Sphinx会根据你自定义的规则生成标题ID，而非默认的s-id{数字}。

总结一下：如果是单个标题需要精准自定义ID，用:name:属性是最直接有效的方法；如果是批量处理非英文标题的ID，就用扩展+自定义slugify函数的方案。

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