Create Page Links

On this page, you’ll learn how to assign the correct resource ID coordinates to an xref macro when:

If you aren’t familiar with the Antora resource ID, its coordinates, or how to use an xref macro, see:

Page links within a module

Most of the cross references you make will probably be between pages that belong to the same module in a component version. The AsciiDoc xref macro only requires the file coordinate of the target page’s resource ID when the current page and target page belong to the same component version and module.

The target page is the page source file that’s being referenced by the current page. The target page is referenced by assigning its resource ID to an xref macro in the content of the current page. The current page is the page source file containing the xref macro that references the target page.

Example 1 shows the file coordinate of the target page assigned to an xref macro in the current page.

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 For step-by-step instructions on how to set up an xref macro, see Make a link with the xref macro.
2 An optional fragment, representing an element ID in the target page, can be assigned after the target page’s file coordinate.

The file coordinate of the target page is always calculated from the root of the pages family directory. That means the structure of the target page’s file coordinate depends on whether the target page is stored at the root of the pages family directory or in a subdirectory of the pages directory.

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 File coordinate of the target page when it’s stored at the root of the pages directory.
2 File coordinate of the target page when it’s stored in a subdirectory of the pages directory, but the current page isn’t stored in the same subdirectory.
3 File coordinate of the target page when the target page and current page are stored in the same subdirectory of the pages directory.

The following sections provide examples of the file coordinate structures.

File coordinate at pages directory root

When the target page is stored at the root of the pages family directory, the file coordinate is the target page’s filename and file extension.

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

Let’s use a few of the pages listed in Example 4 as the basis for the examples in this section.

Example 4. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 pages (3)
      📄 ridge.adoc
      📄 willow-creek.adoc
  📂 ROOT (4)
    📂 pages (5)
      📄 index.adoc
      📄 ranges.adoc
1 Defines the component version as colorado 5.2
2 Defines a module named la-garita
3 Defines subsequent files as pages
4 Defines the ROOT module
5 Defines subsequent files as pages

Using the two pages that belong to the la-garita module, shown in Example 4 above, let’s reference willow-creek.adoc from ridge.adoc. That means the source file willow-creek.adoc is the target page and ridge.adoc is the current page. Example 5 shows an xref macro in the ridge.adoc page that links to the willow-creek.adoc page.

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

The file coordinate for the willow-creek.adoc page consists solely of its filename and file extension, willow-creek.adoc, because it’s stored at the root of the pages directory. The file coordinate of the target page is always calculated from the root of the pages family directory.

Let’s look at another xref macro, shown in Example 6, that references the ranges.adoc page (target page) from the index.adoc page (current page).

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

Only the file coordinate of the target page needs to be specified in the xref macro because both pages belong to the ROOT module and the colorado 5.2 component version. The file coordinate for ranges.adoc is ranges.adoc because it’s stored at the root of the pages directory. See File coordinate with pages-relative directory path and File coordinate with relative path token for file coordinate examples when the target page is stored in a subdirectory pages directory.

File coordinate with pages-relative directory path

The pages-relative directory path of the target page is required in its file coordinate when the current page isn’t stored in the same subdirectory as the target page. If both pages are stored in the same subdirectory, see File coordinate with relative path token.

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]

Let’s reference faq.adoc from ranges.adoc. As you can see in Example 8, both pages belong to the ROOT module of the colorado 5.2 component version.

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 Defines the component version as colorado 5.2
2 Defines the ROOT module
3 Defines subsequent source files as pages
4 A subdirectory in pages containing the source files of pages

The xref macro in Example 9 creates a link to the faq.adoc page (target page) from the ranges.adoc page (current page).

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

As shown in Example 9, the file coordinate for faq.adoc is terms/faq.adoc. The file coordinate assigned to the xref macro consists of the target page’s pages-relative directory path in addition to its filename and file extension because faq.adoc is stored in the subdirectory terms. In cases where the current page and target page are stored in the same subdirectory, you can use the relative path token, ./, in place of the pages-relative directory path.

File coordinate with relative path token

If the target page and current page are stored in the same subdirectory in the pages directory, the pages-relative directory path of the target page’s file coordinate can be replaced with the relative path token, ./.

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]

Let’s reference faq.adoc from signs.adoc. Example 11 shows that both files are stored in the terms subdirectory of the pages directory, and that both files belong to the same module and component version.

Example 11. Directories and files assigned to colorado 5.2
📄 antora.yml
📂 modules
  📂 ROOT (1)
    📂 pages (2)
      📄 index.adoc
      📂 terms (3)
        📄 faq.adoc
        📄 signs.adoc
1 Defines the ROOT module
2 Defines subsequent source files as pages
3 A subdirectory in pages containing the source files of pages

When the target page and current page are stored in the same subdirectory in the pages directory, the relative path token, ./, can be used to abbreviate the target page’s file coordinate. The xref macro in Example 12 links to the faq.adoc page (target page) from the signs.adoc page (current page).

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

As shown in Example 12, the file coordinate for faq.adoc, when referenced from signs.adoc, is ./faq.adoc. Both pages are stored in the terms subdirectory, therefore, the pages-relative directory path of the target page’s file coordinate is replaced with the ./ token.

Page links between modules

When the target page and current page don’t belong to the same module, you must specify the module coordinate and file coordinate of the target page in the xref macro.

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 Assign the module and file coordinates of the target page to the xref macro when the target page and current page belong to the same component version but not the same module.

Using two pages from the colorado 5.2 component version, shown in Example 14, let’s reference ranges.adoc from willow-creek.adoc.

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 Defines the component version as colorado 5.2
2 Defines a module named la-garita
3 Defines the ROOT module

The willow-creek.adoc page belongs to the la-garita module, but ranges.adoc belongs to the ROOT module. The xref macro in Example 15 links to ranges.adoc (target page) from the page willow-creek.adoc (current page).

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

As shown in Example 15, the target page’s module coordinate is ROOT and its file coordinate is ranges.adoc.

Page links between component versions

When the target page and current page belong to different documentation components, you must specify, at a minimum, the target page’s component, module, and file coordinates in the xref macro. You’ll almost always specify the version coordinate, too.

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 Assign the version, component, module, and file coordinates of the target page to the xref macro when the target page and current page don’t belong to the same component versions.
2 If the version coordinate isn’t specified, Antora uses the latest version of the target page’s component to complete the resource ID at runtime. This behavior only applies when the target page and current page belong to different docs components.

Let’s reference elevation.adoc from index.adoc. The index.adoc page belongs to the component version colorado 5.2 (Example 17). The elevation.adoc page belongs to the component version wyoming 1.0 (Example 18).

Example 17. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pages
      📄 willow-creek.adoc
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 ranges.adoc
1 Defines the component version as colorado 5.2
Example 18. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pages
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 Defines the component version as wyoming 1.0

In Example 19, the xref macro links to the elevation.adoc page (target page) from index.adoc (current page) .

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

Because the target page belongs to the wyoming 1.0 component version whereas the current page belongs to colorado 5.2, the resource ID assigned to the xref macro specifies the version, component, module, and file coordinates of the target page. As shown in Example 19, the target page’s version coordinate is 1.0, its component coordinate is wyoming, its module coordinate is sierra-madre, and its file coordinate is elevation.adoc.

In Example 20, the page ranges.adoc is referenced from the page elevation.adoc. The target page, ranges.adoc, belongs to the ROOT module of colorado 5.2 whereas the current page belongs to wyoming 1.0.

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

Notice in Example 20 that the module coordinate ROOT seems to be missing from the resource ID. When a component coordinate is specified in a resource ID, and the target page belongs to the ROOT module, the module coordinate ROOT doesn’t have to be explicitly specified. But you must still enter the colon (:) that would follow the module coordinate. You can see this : directly before the file coordinate ranges.adoc. This shorthand only works when a component coordinate is specified and the module coordinate of the target page is ROOT. In all other cases where the module coordinate is required, the name of the module must be specified.

Link to the latest version of a page

This behavior only applies when the target page and current page belong to different docs components!

If a version isn’t specified in the resource ID assigned to an xref macro, and the target page and current page don’t belong to the same component, Antora uses the version coordinate of the latest version of the target page’s component to complete the resource ID at runtime.

Let’s reference the elevation.adoc page (target page) from the willow-creek.adoc page (current page). elevation.adoc belongs to the component version wyoming 1.0 (Example 21). willow-creek.adoc belongs to component version colorado 5.2 (Example 22) .

Example 21. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pages
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 Defines the component version as wyoming 1.0
Example 22. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pages
      📄 willow-creek.adoc
1 Defines the component version as colorado 5.2

If you always want the xref macro in Example 23 to link to the latest version of the elevation.adoc page, don’t specify a version coordinate in the target page’s resource ID.

Example 23. willow-creek.adoc (current page)
xref:wyoming:sierra-madre:elevation.adoc[How are peaks measured]? (1)
1 Directly after the macro prefix, xref:, assign the resource ID of the target page starting with its component coordinate.

When Antora runs, it will identify wyoming 1.0 as the latest version of the wyoming component according to its version sorting rules and latest version criteria. Because a version coordinate isn’t specified in Example 23, Antora will complete the resource ID assigned to the xref macro using the version coordinate — 1.0 — from the latest wyoming component. Remember, this behavior only applies if the target page and current page belong to different components.

After a few months, let’s add the new component version wyoming 1.5, shown in Example 24, to your site.

Example 24. Directories and files assigned to wyoming 1.5
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pages
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 Defines the component version as wyoming 1.5

The next time the site is generated, Antora will determine that wyoming 1.5 (not wyoming 1.0) is the latest version of the wyoming component.

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

Because Antora now identifies wyoming 1.5 as the latest version of the wyoming component, Antora will complete the resource ID of the target page in Example 25 with the version coordinate — 1.5 — of the latest wyoming component at runtime.

This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target page and current page belong to different components. If the version and component coordinates aren’t specified in the resource ID, Antora assumes the target page belongs to the same component version as the current page and uses the current page’s version and component coordinates to complete the target page’s resource ID.

Page links between versions of a component

When the current page and target page belong to the same component, but the target page belongs to a different version of the component, you’ll specify the version, module (if it’s different than the current page’s module), and file coordinates.

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 Assign the version, module, and file coordinates of the target page to the xref macro when the target page doesn’t belong to the same version and module as the current page.
2 Assign the version and file coordinates of the target page to the xref macro when the target page doesn’t belong to the same version as the current page.

Let’s use the pages that belong to colorado 5.2 (Example 27) and colorado 6.0 (Example 28) as the basis for the example in this section.

Example 27. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 get-started
    📂 pages
      📄 tour.adoc
  📂 la-garita
    📂 pages
      📄 willow-creek.adoc
1 Defines the component version as colorado 5.2
Example 28. Directories and files assigned to colorado 6.0
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pages
      📄 willow-creek.adoc
1 Defines the component version as colorado 6.0

Notice that the colorado 5.2 component version in Example 27 has a tour.adoc page that belongs to the get-started module. However, colorado 6.0, shown in Example 28, has no such module or page. Let’s reference tour.adoc (target page) from the page willow-creek.adoc (current page) that belongs to the colorado 6.0 component version. In Example 29, the resource ID assigned to the xref macro specifies the target page’s version, module, and file coordinates because the target page belongs to a different version and module than the current page.

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

As shown in Example 29, the target page’s version coordinate is 5.2, its module coordinate is get-started, and its file coordinate is tour.adoc.