如何在AsciiDoc中实现跨页面链接并跳转至指定章节

直接用AsciiDoc原生的跨文档锚点能力就行，不需要装插件、改全局配置，两步就能实现：

• 先给目标章节加固定锚点
  打开page2.adoc，找到第2章节的标题行，在标题上方单独加一行显式锚点定义，避免依赖自动生成的锚点（改标题就会失效）：

  [[chapter2]]
  == 这里是你第2章节原来的标题文本
  

  双中括号中间的chapter2是自定义锚点ID，只要整个page2里没有重复ID就可以，随便命名。

• 在page1.adoc里加跳转链接
  优先用xref交叉引用语法，生成HTML/PDF/EPUB等任意格式都能正常跳转：

  xref:page2.adoc#chapter2[点我跳转到page2第2章]
  

  如果只需要在HTML页面里用，也可以用普通link写法，点击后效果一样：

  link:page2.adoc#chapter2[点我跳转到page2第2章]
  

踩坑提示：

• 别省手动加锚点这步，AsciiDoc自动生成的章节锚点会跟着标题文本变，后期改个标题链接直接失效，排查问题很麻烦
• 两个文件不在同一个目录的话，链接里写对page2的相对路径就行，比如page2在content子目录，路径就写content/page2.adoc#chapter2
• 所有基于Asciidoctor的渲染环境（VS Code预览、Antora静态站、官方导出工具等）都原生支持这个写法，点链接直接滚动到对应章节位置，不需要额外配置。

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