内联xref宏还可以链接到其他AsciiDoc文档中的ID。这样就不需要使用特定转换器（例如，HTML链接）之间文档的直接链接，也避免了与转换器的耦合。它还捕获了作者想要在另一个文档中建立一个章节引用的意图。
这是在AsciiDoc中通常定义交叉引用的方式：
Unresolved directive in inter-document-xref.adoc - include::example$xref.adoc[tag=base]这个交叉引用创建了一个链接，指向带有ID anchors 的部分。
假设交叉引用在文档[.path]_document-a.adoc_中定义。如果目标部分位于另一个文档，[.path]_document-b.adoc_中，作者可能会倾向于编写：
Unresolved directive in inter-document-xref.adoc - include::example$xref.adoc[tag=bad]然而，这个链接是和HTML输出相连的。更糟糕的是，如果[.path]_document-b.adoc_被包含在与[.path]_document-a.adoc_相同的文档中，这个链接将会指向一个根本不存在的文档！
这些问题可以通过使用文档间的xref来缓解。
Unresolved directive in inter-document-xref.adoc - include::example$xref.adoc[tag=base-inter]目标的ID现在放置在一个哈希符号（#）之后。在哈希前是参考文档的名字（文件扩展名是可选的）。我们还添加了链接文本，因为AsciiDoc处理器目前还不需要在单独的文档中解析章节标题。
|
Tip
|
虽然本地（即文档内部）交叉引用的链接文本是可选的，但是文档间交叉引用的链接文本（目前）是必须的。 |
当AsciiDoc处理器为这个交叉引用生成链接时，它首先检查[.path]document-b.adoc_是否包含在与[.path]_document-a.adoc_相同的文档中（通过比较xref目标与包含目标相对于最外层文档）。如果不是，它将生成一个链接到[.path]_document-b.html，智能地将原始文件扩展名替换为输出文件的文件扩展名。
<a href="document-b.html#section-b">第B部分</a>如果文件 document-b.adoc 被包含在与 document-a.doc 相同的文档中, 那么在链接目标中将删除该文档，并且看起来像正常交叉引用的输出：
<a href="#section-b">第B部分</a>现在你可以毫无压力地创建文档间的交叉引用。
在源文件之间导航
在某些环境中，例如源代码仓库的网页界面或编辑器预览中，当你访问AsciiDoc源文件的URL时，你可能会看到生成的HTML。如果没有考虑到这一点，这对文档间的交叉引用会有影响。
由于在`html5`后端中，跨文档互相引用的默认后缀是`.html`，因此在这些环境中创建的链接可能会指向不存在的HTML文件。在这种情况下，您需要将跨文档互相引用更改为指向其它AsciiDoc源文件。
文档间交叉引用所选择的文件扩展名由 relfilesuffix 属性控制。默认情况下，此属性未设置，将使用 outfilesuffix 的值代替。如果你想要更改被使用的文件扩展名，你可以通过设置 relfilesuffix 属性来实现。
以下示例演示了如何使用`relfilesuffix`属性来控制文档间交叉引用的文件扩展名，当你想要创建源对源引用时。这个赋值操作是隐藏在一个检查`env-name`背后的，其中`env-name`是一个只在你需要进行这种引用的环境中才会设置的属性。
= 文档标题
ifdef::env-name[:relfilesuffix: .adoc]
查看xref:README.adoc[README]。
我们也可以将链接写成 link:README{relfilesuffix}[README]。生成的文档中的链接现在将指向[.path]README.adoc_而不是[.path]_README.html。
|
Tip
|
这个配置在GitHub、GitLab或浏览器预览扩展上实际上不是必须的，因为这些环境会自动设置`relfilesuffix`的值以匹配源文件的文件扩展名。然而，这个设置可能仍然是其他环境所必需的，所以了解它是有价值的。 |
将引用映射到不同的结构
虽然`relfilesuffix`属性允许你控制文档间交叉引用解析路径的末尾，`relfileprefix`属性则允许你控制路径的开始。在解析文档间交叉引用的路径时，如果设置了`relfileprefix`属性，这个属性的值就会被加到路径的前面。让我们来看一个这两个属性一起使用的示例。
在网站架构的常见实践中，为了使路径格式不依赖具体文件名（称作“索引化”），通常会将文件移到它们自己的文件夹内。例如，路径[.path]filename.html_变为[.path]_filename（这指向[.path]filename/index.html）。但是，这对于文档间的交叉引用是有问题的。任何解析到路径[.path]_filename.html_的交叉引用现在都是无效的，因为文件已经移动到了一个子文件夹（因此不再是引用文档的同级文件了）。
解决这个问题，你可以定义以下两个属性：
:relfileprefix: ../
:relfilesuffix: /现在，交叉引用 <<filename.adoc,link text>> 将解析为 ../filename 而不是 filename.html。由于这种变化是针对所描述的网站架构的特定需求，您需要确保只在那个特定的环境中设置这些属性（要么使用ifdef指令，要么通过API）。