创建页面链接

在本页中，您将学习如何将正确的资源 ID 坐标分配给 xref 宏：

  • 目标页面和当前页面属于相同的组件版本和模块

  • 目标页存储在 pages 目录的根目录中

  • 目标页存储在 pages 目录的子目录中

  • 目标页和当前页存储在 pages 目录的同一子目录中

  • 目标页面和当前页面属于不同的模块

  • 目标页面和当前页面属于不同的组件版本

  • 目标页面和当前页面不属于同一个组件版本，页面链接应该始终使用目标页面的最新版本

  • 目标页面和当前页面属于同一个组件，但目标页面属于不同的版本

如果您不熟悉 Antora 资源ID、它的坐标或如何使用 xref 宏，请参见

在同一个模块中页面链接

您所做的大多数交叉引用可能是在组件版本中属于同一模块的页面之间。当当前页面和目标页面属于同一个组件版本和模块时，AsciiDoc xref 宏只需要目标页面的资源 ID 的文件坐标。

TIP

目标页是当前页引用的页源文件。通过将目标页的资源ID分配给当前页内容中的 xref 宏来引用目标页。当前页面是包含引用目标页面的 xref 宏的页面源文件。

示例1 显示了当前页面中分配给 xref 宏的目标页面的文件坐标。

Example 1. Example 1. current-page.adoc
xref:file-coordinate-of-target-page.adoc[optional link text] (1)

xref:file-coordinate-of-target-page.adoc#fragment[optional link text] (2)
1 有关如何设置 xref 宏的分步说明，请参见 使用 xref 宏创建链接 。
2 一个可选的片段，表示目标页中的一个元素ID，可以在目标页的文件坐标之后分配。

目标页的文件坐标总是从页面族目录的根计算。这意味着目标页文件坐标的结构取决于目标页是存储在 pages 族目录的根目录还是存储在 pages 目录的子目录中。

Example 2. Example 2. File coordinate structure of target page
xref:target-page-filename.adoc[optional link text] (1)

xref:path/to/target-page-filename.adoc[optional link text] (2)

xref:./target-page-filename.adoc[optional link text] (3)
1 目标页存储在 pages 目录的根目录时的文件坐标。
2 当目标页存储在 pages 目录的子目录中，但当前页不存储在同一子目录中时，目标页的文件坐标。
3 当目标页和当前页存储在 pages 目录的同一子目录中时，目标页的文件坐标。

下面几节提供文件坐标结构的示例。

在 pages 目录根的文件坐标

当目标页存储在 pages 族目录的根目录时，文件坐标是目标页的文件名和文件扩展名。

Example 3. Example 3. File coordinate when target page is stored at the root of a pages directory
xref:target-page-filename.adoc[optional link text]

让我们使用示例4中列出的一些页面作为本节示例的基础。

Example 4. Example 4. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 pagesAlian (3)
      📄 ridge.adoc
      📄 willow-creek.adoc
  📂 ROOT (4)
    📂 pagesAlian (5)
      📄 index.adoc
      📄 ranges.adoc
1 将组件版本定义为 colorado 5.2
2 定义一个名为 la-garita 的模块
3 在页面(pages)目录创建页面
4 定义 ROOT 目录
5 在 pages 目录创建页面

使用上面示例4中属于 la-garita 模块的两个页面，让我们从 ridge.adoc 引用 willow-creek.adoc 。这意味着源文件 willow-creek.adoc 是目标页面，而 ridge.adoc 是当前页面。示例5显示了在 ridge.adoc 页面中链接到 willow-creek.adoc 页面的 xref 宏。

Example 5. Example 5. ridge.adoc (current page)
The xref:willow-creek.adoc[trailhead] is north of town.

willow-creek.adoc 页面的文件坐标仅由其文件名和文件扩展名 willow-creek.adoc 构成，因为它存储在 pages 目录的根目录中。目标页面的文件坐标始终是从 pages 族目录的根目录计算的。

让我们看一下示例6中显示的另一个 xref 宏，该 xref 宏在 index.adoc 页面(当前页面)引用了 ranges.adoc 页面(目标页面)。

Example 6. Example 6. index.adoc (current page)
The Rocky Mountains consists of xref:ranges.adoc[numerous mountain ranges].

只有目标页面的文件坐标需要在 xref 宏中指定，因为这两个页面都属于 ROOT 模块和 colorado 5.2 组件版本。ranges.adoc 的文件坐标是 ranges.adoc ，因为它存储在 pages 目录的根目录中。当目标页面存储在子目录 pages 目录中时，请参见文件与页面相对目录路径的文件坐标和文件与相对路径标记的文件坐标示例。

pages 相对目录路径的文件坐标

当当前页不与目标页存储在同一子目录中时，目标页的页相对目录路径在其文件坐标中是必需的。如果两个页面都存储在同一子目录中，请参阅使用相对路径令牌的文件坐标。

Example 7. Example 7. File coordinate when the target page is stored in a subdirectory of a pages directory
xref:path/to/target-page-filename.adoc[optional link text]

让我们参考来自 ranges.adoc 的 faq.adoc 。在示例8中可以看到，这两个页面都属于 colorado 5.2 组件版本的 ROOT 模块。

Example 8. Example 8. Directories and files assigned to colorado 5.2
📄 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 在 pages 目录中创建页面
4 pages 中的子目录，包含页面的源文件

例9中的 xref 宏从 ranges.adoc (当前页面)创建了一个链接到 faq.adoc 页面(目标页面)的链接。

Example 9. Example 9. ranges.adoc (current page)
See the xref:terms/faq.adoc[].

如示例9所示，faq.adoc 文件的文件路径为 terms/faq.adoc 。分配给 xref 宏的文件路径包括目标页面相对于页面的目录路径以及其文件名和文件扩展名，因为 faq.adoc 存储在子目录 terms 中。如果当前页面和目标页面存储在同一子目录中，则可以使用相对路径符号 ./ 代替页面相对路径。

带有相对路径标记的文件坐标

如果目标页面和当前页面存储在页面目录中的同一子目录中，则可以将目标页面文件坐标的页面相关目录路径替换为相对路径符号，./ 。

Example 10. Example 10. File coordinate when the target page and current page are stored in the same subdirectory
xref:./target-page-filename.adoc[optional link text]

让我们从 signs.adoc 引用 faq.adoc 。示例11显示，两个文件都存储在页面目录的 terms 子目录中，并且两个文件都属于同一个模块和组件版本。

Example 11. Example 11. Directories and files assigned to colorado 5.2
📄 antora.yml
📂 modules
  📂 ROOT (1)
    📂 pagesAlian (2)
      📄 index.adoc
      📂 terms (3)
        📄 faq.adoc
        📄 signs.adoc
1 定义 ROOT 模块
2 在 pages 目录创建页面
3 pages 中的子目录，包含页面的源文件

当目标页面和当前页面存储在页面目录的同一子目录中时，可以使用相对路径符号 ./ 缩写目标页面的文件路径。示例12中的 xref 宏从 signs.adoc 页面（当前页面）链接到 faq.adoc 页面（目标页面）。

Example 12. Example 12. signs.adoc (current page)
See the xref:./faq.adoc[].

如示例12所示，当从 signs.adoc 引用 faq.adoc 时，faq.adoc 的文件路径为 ./faq.adoc 。两个页面都存储在 terms 子目录中，因此目标页面的文件路径的相对目录路径被替换为 ./ 符号。

在不同模块中页面链接

当目标页和当前页不属于同一个模块时，必须在 xref 宏中指定目标页的模块坐标和文件坐标。

Example 13. Example 13. Module and file coordinate of target page assigned to an xref macro
xref:module:file-coordinate-of-target-page.adoc[optional link text] (1)
1 当目标页面和当前页面属于相同的组件版本但不属于相同的模块时，将目标页面的模块和文件坐标分配给 xref 宏。

使用 colorado 5.2 组件版本中的两个页面，如示例14所示，让我们在 willow-creek.adoc (当前页面)中引用 ranges.adoc (目标页面)。

Example 14. Example 14. Directories and files assigned to colorado 5.2
📄 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 宏从页面 willow-creek.adoc（当前页面）链接到 ranges.adoc 页面（目标页面）。

Example 15. Example 15. willow-creek.adoc (current page)
Only xref:ROOT:ranges.adoc[one pass is open] in the winter.

如示例15所示，目标页面的模块坐标是 ROOT ，其文件坐标是 range.adoc 。

在不同组件版本中页面链接

当目标页面和当前页面属于不同的文档组件时，您必须在 xref 宏中指定至少目标页面的组件、模块和文件路径坐标。您几乎总是也会指定版本坐标。

Example 16. Example 16. Version, component, module, and file coordinates assigned to an xref macro
xref:version@component:module:file-coordinate-of-target-page.adoc[optional link text] (1)

xref:component:module:file-coordinate-of-target-page.adoc[optional link text] (2)
1 当目标页面和当前页面不属于相同的组件版本时，将目标页面的版本、组件、模块和文件坐标分配给 xref 宏。
2 如果没有指定版本坐标，Antora 将在运行时使用目标页面组件的最新版本来完成资源ID。此行为仅适用于目标页面和当前页面属于不同文档组件的情况。

让我们从 index.adoc 引用 elevation.adoc 。index.adoc 页面属于组件版本 colorado 5.2 （示例17）。elevation.adoc 页面属于组件版本 wyoming 1.0（示例18）。

Example 17. Example 17. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pagesAlian
      📄 willow-creek.adoc
  📂 ROOT
    📂 pagesAlian
      📄 index.adoc
      📄 ranges.adoc
1 将组件版本定义为colorado 5.2
Example 18. Example 18. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pagesAlian
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 将组件版本定义为 wyoming 1.0

在示例19中，xref 宏从 index.adoc (当前页面) 链接到 elevation.adoc (目标页面) 。

Example 19. Example 19. index.adoc (current page)
Do you know xref:1.0@wyoming:sierra-madre:elevation.adoc[how elevation is measured]?

因为目标页面属于 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 。

Example 20. Example 20. elevation.adoc (current page)
xref:5.2@colorado::ranges.adoc[]

请注意，在示例20中，资源ID中似乎缺少了模块坐标 ROOT 。当在资源ID中指定了组件坐标，并且目标页面属于 ROOT 模块时，无需显式指定模块坐标 ROOT 。但是，您仍必须输入模块坐标后跟随的冒号（ : ）。在文件路径坐标 ranges.adoc 之前，可以看到这个冒号。这种简写方式仅适用于指定组件坐标且目标页面的模块坐标为 ROOT 的情况。在所有其他需要模块坐标的情况下，必须指定模块的名称。

链接到一个页面的最新版本

TIP

此行为仅适用于目标页面和当前页面属于不同文档组件的情况

如果在分配给 xref 宏的资源ID中未指定版本，且目标页面和当前页面不属于同一组件，则 Antora 在运行时使用目标页面组件的最新版本的版本坐标来完成资源ID。

让我们从 willow-creek.adoc 页面（当前页面）引用 elevation.adoc 页面（目标页面）。elevation.adoc 属于组件版本 wyoming 1.0 （示例21）。willow-creek.adoc 属于组件版本 colorado 5.2（示例22）。

Example 21. Example 21. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pagesAlian
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 将组件版本定义为 wyoming 1.0
Example 22. Example 22. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pagesAlian
      📄 willow-creek.adoc
1 将组件版本定义为 colorado 5.2

如果您希望示例23中的 xref 宏始终链接到 elevation.adoc 页面的最新版本，则不要在目标页面的资源ID中指定版本坐标。

Example 23. Example 23. willow-creek.adoc (current page)
xref:wyoming:sierra-madre:elevation.adoc[How are peaks measured]? (1)
1 直接在宏前缀 xref: 之后，分配目标页面的资源ID，从其组件坐标开始。

当 Antora 运行时，它将根据其版本排序规则和最新版本标准将 wyoming 1.0 确定为 wyoming 组件的最新版本。因为示例23中未指定版本坐标，Antora 将使用最新的 wyoming 组件的版本坐标 1.0 完成分配给 xref 宏的资源ID。请记住，此行为仅适用于目标页面和当前页面属于不同组件的情况。

几个月后，让我们将新组件版本 wyoming 1.5 添加到站点，如例24所示。

Example 24. Example 24. Directories and files assigned to wyoming 1.5
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pagesAlian
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 定义组件版本为 wyoming 1.5

下次生成站点时，Antora 将确定 wyoming 1.5（而不是 wyoming 1.0 ）是 wyoming 组件的最新版本。

Example 25. Example 25. willow-creek.adoc (current page)
xref:wyoming:sierra-madre:elevation.adoc[How are peaks measured]?

由于 Antora 现在将 wyoming 1.5 识别为 wyoming 组件的最新版本，因此 Antora 将在运行时使用最新 wyoming 组件的版本坐标 1.5 来完成示例25中目标页面的资源ID。

WARNING

仅当未指定版本坐标且目标页面和当前页面属于不同组件时，链接到最新版本的此行为才适用。如果在资源ID中未指定版本和组件坐标，则 Antora 假定目标页面属于与当前页面相同的组件版本，并使用当前页面的版本和组件坐标来完成目标页面的资源ID。

同一个组件，不同版本的页面链接

当当前页面和目标页面属于同一个组件，但目标页面属于组件的不同版本时，您将指定版本、模块(如果它与当前页面的模块不同)和文件坐标。

Example 26. Example 26. current-page.adoc
xref:version@module:file-coordinate-of-target-page.adoc[optional link text] (1)

xref:version@file-coordinate-of-target-page.adoc[optional link text] (2)
1 当目标页与当前页不属于相同的版本和模块时，将目标页的版本、模块和文件坐标分配给 xref 宏。
2 当目标页与当前页属于不同的版本时，将目标页的版本和文件坐标分配给 xref 宏。

让我们使用属于 colorado 5.2 (例27)和 colorado 6.0 (例28)的页面作为本节示例的基础。

Example 27. Example 27. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 get-started
    📂 pagesAlian
      📄 tour.adoc
  📂 la-garita
    📂 pagesAlian
      📄 willow-creek.adoc
1 将组件版本定义为 colorado 5.2
Example 28. Example 28. Directories and files assigned to colorado 6.0
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pagesAlian
      📄 willow-creek.adoc
1 将组件版本定义为 colorado 6.0

请注意，示例27中的 colorado 5.2 组件版本具有属于 get-started 模块的 tour.adoc 页面。但是，示例28中的 colorado 6.0 没有此类模块或页面。让我们从属于 colorado 6.0 组件版本的 willow-creek.adoc 页面（当前页面）引用 tour.adoc 页面（目标页面）。在示例29中，分配给 xref 宏的资源ID指定了目标页面的版本、模块和文件路径坐标，因为目标页面属于与当前页面不同的版本和模块。

Example 29. Example 29. willow-creek.adoc (current page) in colorado 6.0
Last year's xref:5.2@get-started:tour.adoc[excursions] were riveting!

如示例29所示，目标页面的版本坐标为 5.2 ，模块坐标为 get-started ，文件路径坐标为 tour.adoc 。