Xref Pages in Other Components and Versions

When the current and target pages belong to different docs components, you must, at a minimum, specify the target component, module, and page coordinates. You’ll almost always specify the target version coordinate, too.

For context, let’s use the pages that belong to the component versions colorado 5.2 and wyoming 1.0 as the basis for the examples on this section. Their source files are stored in the standard directory trees listed in Example 2.

Example 3 shows an xref in the page index.adoc (current page) that links to the elevation.adoc page (target page). index.adoc belongs to version 5.2 of the component colorado. elevation.adoc belongs to version 1.0 of the component wyoming.

When the xref in Example 3 is converted, it will become a link to the published site page at https://base-url.com/wyoming/1.0/sierra-madre/elevation.html.

In Example 4, the page ranges.adoc is referenced from the page elevation.adoc (current page). The target page, ranges.adoc, belongs to the ROOT module of the colorado component.

Notice in Example 4 that the module name ROOT seems to be missing from the page ID. When a component coordinate is specified in a page 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 page coordinate ranges.adoc. This shorthand only works when a component coordinate is specified and the target module is ROOT. In all other cases where the target module coordinate is required, the name of the module must be specified.

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

If the target and current pages belong to the same module, too, then you only need to specify the target version and page coordinates.

For context, let’s use the pages that belong to the component versions colorado 5.2 and colorado 6.0 as the basis for the example in this section. Their source files are stored in the standard directory trees listed in Example 8.

Notice that the colorado 5.2 component version has a tour.adoc page that belongs to the get-started module. However, colorado 6.0 has no such module or page.

Let’s reference the page tour.adoc (target page), which belongs to colorado 5.2, from the page cochetopa-pass.adoc (current page), which belongs to the colorado 6.0 component version. In Example 9, the xref specifies the target page’s version, module, and page coordinates.

When the xref in Example 9 is converted by Antora, it will become a link to the published site page at https://base-url.com/colorado/5.2/get-started/tour.html.