文档开头已经定义了一条引用式链接,后面为了更新地址又写一条同名定义,页面却继续跳到旧地址。排查时先搜索整个文档的链接标签:引用式定义有自己的匹配与优先级规则,后一条未必覆盖前一条。

2026年11月20日,在Markdown转HTML工具输入下面的公开演示,两个目标都是用于观察源码的相对路径:

[指南][Doc]

[doc]: /first
[DOC]: /second

本次生成的a标签使用/first,页面里的链接文字为“指南”。定义行本身没有变成两个可见段落,判断目标应看生成的href。

当前输出的指南链接指向第一条定义的/first,后面的/second没有覆盖它
当前输出的指南链接指向第一条定义的/first,后面的/second没有覆盖它

同名标签按规范匹配

CommonMark的引用标签匹配会处理大小写等差异。本例Doc、doc和DOC命中同一个标签;多条有效定义匹配时,第一条优先。因此,仅把定义名改成大写,仍然无法让这两项各自独立。

第二组把标签明确改为one与two,工具分别生成/first和/second。本机读取生成HTML的a节点,也得到两条独立的文字与href,结果便于逐项核对。

本机整理两组实际HTML中的链接文字和href,展示同名优先与不同标签分别绑定的结果
本机整理两组实际HTML中的链接文字和href,展示同名优先与不同标签分别绑定的结果

更新时找到实际生效的定义

如果整篇只需要一个目标,直接修改第一条有效定义,并清理已经不用的同名项。若两个位置确实应跳到不同目标,就为它们分配不同标签,再检查所有引用处。这样能让正文中的简短引用与末尾定义保持一一对应。

复制大段文档时尤其要留意原文末尾的定义区。链接文字看起来相同,实际href仍可能来自更早的一行;编辑预览后应检查输出源码。基础操作可以参考Markdown转HTML的源码核对,正式发布时再确认目标路径在站点中可用。