DITA-OT本地XREF引用失效：同页面锚点链接ID不匹配求助

• 检查目标元素ID合法性

  • DITA要求ID必须符合XML命名规则：不能以数字开头，不能包含空格或除下划线、连字符、句点外的特殊字符。若ID不规范，转换工具会自动修正（如加前缀、替换字符），导致XREF中的ID与生成的HTML元素ID不一致。
  • 确认id属性直接定义在跳转目标元素上（如<section id="target-id">），而非其父容器或子元素。

• 验证XREF格式正确性

  • 严格遵循#[topic-id]/[target-id]格式，其中topic-id是当前主题根元素的ID（同页跳转时即当前文件<topic>/<concept>等根元素的id），不可遗漏或写错。
  • 检查ID拼写与大小写：XML大小写敏感，转换后的HTML会保留大小写，XREF中的ID需与目标元素ID完全一致。

• 查看转换日志信息

  • 运行转换时开启详细日志（DITA-OT用-v参数，Oxygen在转换场景勾选“显示详细日志”），搜索ID相关的警告/错误，比如“ID冲突”“无效ID被重命名”等提示，工具可能因ID冲突自动修改目标ID。

• 排查ID冲突问题

  • 检查整个DITA项目中是否存在重复ID，DITA-OT转换时会为冲突ID添加后缀（如target-id_1），导致XREF指向的原始ID不存在。
  • 用Oxygen的全局查找功能搜索重复ID，或使用dita validate命令检查ID唯一性。

• 检查自定义转换模板

  • 若使用了自定义XHTML转换模板（修改过xref处理的XSLT），确认模板是否对XREF目标ID或元素ID生成逻辑做了额外处理（如加前缀、格式转换）。
  • 对比默认转换模板的输出，排除自定义模板导致的问题。

• 确认目标元素的转换结果

  • 部分DITA元素（如<note>、<fig>）转换后会被包装到HTML容器中，实际锚点ID可能在容器元素上。查看生成的HTML源码，确认目标锚点的真实ID值。

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