Create Page Links

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.

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

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.

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).

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.

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.

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.

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

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.

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, ./.

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.

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).

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.

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) .

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.

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.

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.

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.