Rst语法中如何正确使用:doi:、:arxiv:链接指令避免链接失效

:doi: 和 :arxiv: 不属于 RST 原生内置的语法角色，需要搭配对应的扩展才能正常使用，以常用的 Sphinx 文档构建工具为例，配置和使用方法如下：

1. 配置扩展 #

你可以使用官方的 sphinx.ext.extlinks 扩展快速自定义这两个链接角色，操作步骤如下：

• 打开项目的 conf.py 配置文件，先将扩展添加到扩展列表中：

extensions = [
    # 保留你原本已启用的其他扩展
    "sphinx.ext.extlinks",
]

• 在 conf.py 中新增 extlinks 配置项，定义两个角色的链接规则：

extlinks = {
    # 第一个参数是链接拼接规则，%s 会替换为你写的编号；第二个参数是链接显示文本格式
    "doi": ("https://doi.org/%s", "DOI: %s"),
    "arxiv": ("https://arxiv.org/abs/%s", "arXiv: %s"),
}

如果你需要更复杂的文献引用能力，也可以选择第三方扩展如 sphinxcontrib-bibtex，在 bib 文献库中对应条目的 doi、eprint 字段填写编号即可自动生成链接。

2. 正确的调用语法 #

你之前的写法中多余的外层尖括号会导致解析失败，正确的正文调用写法如下：

# 引用DOI
:doi:`10.1145/2487575.2487591`

# 引用arXiv编号
:arxiv:`1309.0238`

常见排查点 #

• 确认构建工具已正确加载对应扩展，未加载的情况下RST会将角色识别为普通文本或抛出未知角色报错
• 非Sphinx的RST渲染器需要确认是否支持自定义角色或对应扩展，原生RST本身没有内置这两个链接角色

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