创建页面链接
在这个页面上，您将学习如何在以下情况下为 xref 宏分配正确的资源 ID 坐标：
-
目标页面和当前页面属于同一组件版本和模块
-
目标页面存储在pages目录的根目录
-
目标页面存储在pages目录的子目录中
-
目标页面和当前页面存储在pages目录的同一子目录中
-
目标页面和当前页面属于不同的模块
-
目标页面和当前页面属于不同的组件版本
-
目标页面和当前页面不属于同一组件版本，并且页面链接应始终使用目标页面的最新版本
-
目标页面和当前页面属于同一组件，但目标页面属于不同版本
|
如果您不熟悉 Antora 资源 ID、其坐标或如何使用 xref 宏，请参阅： |
模块内的页面链接
示例1显示了将目标页面的文件坐标分配给当前页面中的xref宏。
xref:file-coordinate-of-target-page.adoc[可选链接文本] (1)
xref:file-coordinate-of-target-page.adoc#fragment[可选链接文本] (2)| 1 | 有关如何设置xref宏的逐步说明，请参见使用xref宏创建链接。 |
| 2 | 可以在目标页面的文件坐标之后分配一个可选片段，表示目标页面中的元素ID。 |
目标页面的文件坐标始终是从pages家族目录的根目录计算的。这意味着目标页面的文件坐标结构取决于目标页面是存储在pages家族目录的根目录还是存储在pages目录的子目录中。
xref:target-page-filename.adoc[可选链接文本] (1)
xref:path/to/target-page-filename.adoc[可选链接文本] (2)
xref:./target-page-filename.adoc[可选链接文本] (3)| 1 | 当目标页面存储在pages目录的根目录时的目标页面的文件坐标。 |
| 2 | 当目标页面存储在pages目录的子目录中，但当前页面未存储在相同子目录中时的目标页面的文件坐标。 |
| 3 | 当目标页面和当前页面存储在pages目录的相同子目录中时的目标页面的文件坐标。 |
以下部分提供了文件坐标结构的示例。
在pages目录根目录的文件坐标
当目标页面存储在pages家族目录的根目录时，文件坐标是目标页面的文件名和文件扩展名。
xref:target-page-filename.adoc[可选链接文本]让我们以示例4中列出的一些页面为基础，来看看本节示例中的示例。
📄 antora.yml (1)
📂 modules
📂 la-garita (2)
📂 pages (3)
📄 ridge.adoc
📄 willow-creek.adoc
📂 ROOT (4)
📂 pages (5)
📄 index.adoc
📄 ranges.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义名为la-garita的模块 |
| 3 | 将后续文件定义为页面 |
| 4 | 定义ROOT模块 |
| 5 | 将后续文件定义为页面 |
使用示例4中属于la-garita模块的两个页面作为基础，让我们从ridge.adoc引用willow-creek.adoc。这意味着源文件willow-creek.adoc是目标页面，ridge.adoc是当前页面。示例5显示了ridge.adoc页面中的一个xref宏，链接到willow-creek.adoc页面。
xref:willow-creek.adoc[trailhead] 在城镇的北部。willow-creek.adoc页面的文件坐标仅包括其文件名和文件扩展名，willow-creek.adoc，因为它存储在pages目录的根目录。目标页面的文件坐标始终是从pages家族目录的根目录计算的。
让我们看另一个xref宏，如示例6所示，引用ranges.adoc页面（目标页面）从index.adoc页面（当前页面）。
落基山脉由xref:ranges.adoc[众多山脉]组成。只需要在xref宏中指定目标页面的文件坐标，因为两个页面都属于ROOT模块和colorado 5.2组件版本。 ranges.adoc的文件坐标是ranges.adoc，因为它存储在pages目录的根目录。有关当目标页面存储在pages目录的子目录中时的文件坐标示例，请参见具有pages相对目录路径的文件坐标和具有相对路径标记的文件坐标。
文件与页面相对目录路径协调
当目标页面不存储在与当前页面相同的子目录中时，当前页面的pages相对目录路径在其文件坐标中是必需的。如果两个页面存储在同一子目录中，请参阅使用相对路径标记的文件坐标。
xref:path/to/target-page-filename.adoc[可选链接文本]让我们从ranges.adoc引用faq.adoc。正如您在示例8中所看到的，这两个页面都属于colorado 5.2组件版本的ROOT模块。
📄 antora.yml (1)
📂 modules
📂 ROOT (2)
📂 pages (3)
📄 index.adoc
📄 ranges.adoc
📂 terms (4)
📄 faq.adoc
📄 signs.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义ROOT模块 |
| 3 | 将后续源文件定义为页面 |
| 4 | pages中包含页面源文件的子目录 |
示例9中的xref宏创建了一个链接，从ranges.adoc页面（当前页面）到faq.adoc页面（目标页面）。
查看xref:terms/faq.adoc[]。如示例9所示，当从signs.adoc引用时，faq.adoc的文件坐标为terms/faq.adoc。xref宏分配给的文件坐标由目标页面的pages相对目录路径以及其文件名和文件扩展名组成，因为faq.adoc存储在子目录terms中。在当前页面和目标页面存储在同一子目录中的情况下，您可以使用相对路径标记./来代替pages相对目录路径。
使用相对路径标记的文件坐标
xref:./target-page-filename.adoc[可选链接文本]让我们从signs.adoc引用faq.adoc。如示例11所示，这两个文件都存储在pages目录的terms子目录中，并且这两个文件属于同一模块和组件版本。
📄 antora.yml
📂 modules
📂 ROOT (1)
📂 pages (2)
📄 index.adoc
📂 terms (3)
📄 faq.adoc
📄 signs.adoc
| 1 | 定义ROOT模块 |
| 2 | 将后续源文件定义为页面 |
| 3 | pages中包含页面源文件的子目录 |
当目标页面和当前页面存储在pages目录中的同一子目录中时，可以使用相对路径标记./来缩写目标页面的文件坐标。在示例12中的xref宏链接到faq.adoc页面（目标页面）从signs.adoc页面（当前页面）。
查看xref:./faq.adoc[]。如示例12所示，当从signs.adoc引用时，faq.adoc的文件坐标为./faq.adoc。由于这两个页面存储在terms子目录中，因此目标页面的文件坐标的pages相对目录路径被./标记替换。
模块之间的页面链接
xref:module:file-coordinate-of-target-page.adoc[可选链接文本] (1)| 1 | 当目标页面和当前页面属于同一组件版本但不属于同一模块时，将目标页面的模块和文件坐标分配给xref宏。 |
使用colorado 5.2组件版本中的两个页面，如ranges.adoc从willow-creek.adoc引用，如示例14中所示。
📄 antora.yml (1)
📂 modules
📂 la-garita (2)
📂 pages
📄 willow-creek.adoc
📂 ROOT (3)
📂 pages
📄 index.adoc
📄 ranges.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义名为la-garita的模块 |
| 3 | 定义ROOT模块 |
willow-creek.adoc页面属于la-garita模块，但ranges.adoc属于ROOT模块。示例15中的xref宏链接到ranges.adoc（目标页面）从页面willow-creek.adoc（当前页面）。
只有在冬天打开xref:ROOT:ranges.adoc[一个通道]。如示例15所示，目标页面的模块坐标为ROOT，文件坐标为ranges.adoc。
组件版本之间的页面链接
当目标页面和当前页面属于不同的文档组件时，您必须在xref宏中至少指定目标页面的组件、模块和文件坐标。通常也会指定版本坐标。
xref:version@component:module:file-coordinate-of-target-page.adoc[可选链接文本] (1)
xref:component:module:file-coordinate-of-target-page.adoc[可选链接文本] (2)| 1 | 当目标页面和当前页面不属于相同的组件版本时，将目标页面的版本、组件、模块和文件坐标分配给xref宏。 |
| 2 | 如果未指定版本坐标，Antora将使用目标页面组件的最新版本在运行时完成资源ID。此行为仅适用于目标页面和当前页面属于不同文档组件的情况。 |
让我们从index.adoc引用elevation.adoc。 index.adoc 页面属于组件版本colorado 5.2（示例17）。 elevation.adoc 页面属于组件版本wyoming 1.0（示例18）。
📄 antora.yml (1)
📂 modules
📂 la-garita
📂 pages
📄 willow-creek.adoc
📂 ROOT
📂 pages
📄 index.adoc
📄 ranges.adoc
| 1 | 将组件版本定义为colorado 5.2 |
📄 antora.yml (1)
📂 modules
📂 sierra-madre
📂 pages
📄 elevation.adoc
📄 wilderness-areas.adoc
| 1 | 将组件版本定义为wyoming 1.0 |
在示例19中，xref宏链接到elevation.adoc页面（目标页面）从index.adoc页面（当前页面）。
你知道xref:1.0@wyoming:sierra-madre:elevation.adoc[如何测量海拔]吗？由于目标页面属于wyoming 1.0组件版本，而当前页面属于colorado 5.2，因此分配给xref宏的资源ID指定了目标页面的版本、组件、模块和文件坐标。如示例19所示，目标页面的版本坐标为1.0，组件坐标为wyoming，模块坐标为sierra-madre，文件坐标为elevation.adoc。
在示例20中，从页面elevation.adoc引用了页面ranges.adoc。目标页面ranges.adoc属于colorado 5.2的ROOT模块，而当前页面属于wyoming 1.0。
xref:5.2@colorado::ranges.adoc[]请注意，在示例20中，模块坐标ROOT似乎在资源ID中缺失。当在资源ID中指定组件坐标，并且目标页面属于ROOT模块时，不必显式指定模块坐标ROOT。但仍需输入紧随模块坐标之后的冒号:。您可以在文件坐标ranges.adoc之前直接看到这个:。这种简写仅在指定组件坐标且目标页面的模块坐标为ROOT时有效。在其他所有需要模块坐标的情况下，必须指定模块的名称。
链接到页面的最新版本
| 此行为仅适用于目标页面和当前页面属于不同文档组件的情况！ |
如果在分配给xref宏的资源ID中未指定版本，并且目标页面和当前页面不属于同一组件，则Antora将在运行时使用目标页面组件的最新版本的版本坐标来完成资源ID。
让我们从willow-creek.adoc页面（当前页面）引用elevation.adoc页面（目标页面）。elevation.adoc属于组件版本wyoming 1.0（示例21）。willow-creek.adoc属于组件版本colorado 5.2（示例22）。
📄 antora.yml (1)
📂 modules
📂 sierra-madre
📂 pages
📄 elevation.adoc
📄 wilderness-areas.adoc
| 1 | 将组件版本定义为wyoming 1.0 |
📄 antora.yml (1)
📂 modules
📂 la-garita
📂 pages
📄 willow-creek.adoc
| 1 | 将组件版本定义为colorado 5.2 |
如果您希望示例23中的xref宏始终链接到elevation.adoc页面的最新版本，请不要在目标页面的资源ID中指定版本坐标。
xref:wyoming:sierra-madre:elevation.adoc[峰值如何测量]? (1)| 1 | 在宏前缀xref:之后，直接分配目标页面的资源ID，从其组件坐标开始。 |
当Antora运行时，它将根据其版本排序规则和最新版本标准确定wyoming组件的最新版本为wyoming 1.0。因为在示例23中未指定版本坐标，Antora将使用最新wyoming组件的版本坐标1.0来完成分配给xref宏的资源ID。请记住，此行为仅适用于目标页面和当前页面属于不同组件的情况。
几个月后，让我们将新的组件版本wyoming 1.5（在示例24中显示）添加到您的站点。
📄 antora.yml (1)
📂 modules
📂 sierra-madre
📂 pages
📄 elevation.adoc
📄 wilderness-areas.adoc
| 1 | 将组件版本定义为wyoming 1.5 |
下次生成站点时，Antora将确定wyoming 1.5（而不是wyoming 1.0）是wyoming组件的最新版本。
xref:wyoming:sierra-madre:elevation.adoc[峰值如何测量]?因为Antora现在将wyoming 1.5识别为wyoming组件的最新版本，所以Antora将在示例25中完成目标页面的资源ID，使用最新wyoming组件的版本坐标1.5。
| 仅当未指定版本坐标且目标页面和当前页面属于不同组件时，才适用链接到最新版本的此行为。如果在资源ID中未指定版本和组件坐标，则Antora会假定目标页面属于与当前页面相同的组件版本，并使用当前页面的版本和组件坐标来完成目标页面的资源ID。 |
组件版本之间的页面链接
xref:version@module:file-coordinate-of-target-page.adoc[可选链接文本] (1)
xref:version@file-coordinate-of-target-page.adoc[可选链接文本] (2)| 1 | 当目标页面不属于与当前页面相同版本和模块时，将目标页面的版本、模块和文件坐标分配给xref宏。 |
| 2 | 当目标页面不属于与当前页面相同版本时，将目标页面的版本和文件坐标分配给xref宏。 |
📄 antora.yml (1)
📂 modules
📂 get-started
📂 pages
📄 tour.adoc
📂 la-garita
📂 pages
📄 willow-creek.adoc
| 1 | 将组件版本定义为colorado 5.2 |
📄 antora.yml (1)
📂 modules
📂 la-garita
📂 pages
📄 willow-creek.adoc
| 1 | 将组件版本定义为colorado 6.0 |
请注意，在colorado 5.2组件版本中的示例 27中，有一个属于get-started模块的tour.adoc页面。然而，在colorado 6.0，如示例 28所示，没有这样的模块或页面。让我们从属于colorado 6.0组件版本的页面willow-creek.adoc（当前页面）引用tour.adoc（目标页面）。在示例 29中，分配给xref宏的资源ID指定了目标页面的版本、模块和文件坐标，因为目标页面属于与当前页面不同的版本和模块。
去年的xref:5.2@get-started:tour.adoc[游览]令人着迷！如示例 29所示，目标页面的版本坐标为5.2，模块坐标为get-started，文件坐标为tour.adoc。