Xref Pages in Other Components and Versions

Sometimes you’ll need to create cross references between pages that belong to different docs components. In these cases, you’ll often construct a fully qualified page ID. You can also create xrefs between pages that belong to different versions of the same component.

Xref pages from other docs components

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.

Example 1. current-page.adoc
xref:version@component:module:target-page-filename.adoc[link text]

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 2. Standard directories assigned to the component versions colorado 5.2 and wyoming 1.0
📒 repository
  📄 antora.yml <- Declares files belong to colorado 5.2
  📂 modules
    📂 get-started
      📂 pages
        📄 tour.adoc
    📂 la-garita
      📂 pages
        📄 cochetopa-pass.adoc
    📂 ROOT
      📂 pages
        📄 index.adoc
        📄 ranges.adoc

📒 repository
  📂 docs
    📄 antora.yml <- Declares files belong to wyoming 1.0
    📂 modules
      📂 sierra-madre
        📂 pages
          📄 elevation.adoc
          📄 wilderness-areas.adoc

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.

Example 3. index.adoc (current page)
See xref:1.0@wyoming:sierra-madre:elevation.adoc[How are peaks measured]?

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.

Example 4. elevation.adoc (current page)
xref:5.2@colorado::ranges.adoc[List of ranges by height]

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.

Xref the latest version of a page

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

If a version isn’t specified in the target page ID, and the target and current pages belong to a different docs components, Antora will use the latest version of the target component to complete the page ID.

Using the component versions previously described in Example 2, let’s create an xref in the page index.adoc (current page) that links to the elevation.adoc page (target page). The xref is shown below in Example 5. index.adoc belongs to version 5.2 of the component colorado. elevation.adoc belongs to version 1.0 of the component wyoming. Notice that the target page’s version coordinate isn’t specified.

Example 5. index.adoc (current page)
See xref:wyoming:sierra-madre:elevation.adoc[How are peaks measured]?

Since there isn’t a version coordinate in Example 5, Antora will automatically complete the page ID at runtime using the latest version — 1.0 — of the wyoming component. When you release a newer version of wyoming, such as version 1.5, and add it to your site, the xref in Example 5 will automatically link to the elevation.adoc page in version 1.5 of wyoming.

This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target and current pages belong to different components. If you don’t specify a version and a component in the page ID, Antora assumes the target page’s version and component are the same as the current page’s version and component coordinates.

Xref pages from other versions

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.

Example 6. current-page.adoc
xref:version@module:target-page-filename.adoc[link text]

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

Example 7. current-page.adoc
xref:version@target-page-filename.adoc[link text]

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.

Example 8. Standard directories assigned to the component versions colorado 5.2 and colorado 6.0
📒 repository | branch name v5.2.x
  📄 antora.yml <- Declares files belong to colorado 5.2
  📂 modules
    📂 get-started
      📂 pages
        📄 tour.adoc
    📂 la-garita
      📂 pages
        📄 cochetopa-pass.adoc
    📂 ROOT
      📂 pages
        📄 index.adoc
        📄 ranges.adoc

📒 repository | branch name v6.0.x
  📄 antora.yml <- Declares files belong to colorado 6.0
  📂 modules
    📂 la-garita
      📂 pages
        📄 cochetopa-pass.adoc
    📂 ROOT
      📂 pages
        📄 index.adoc
        📄 ranges.adoc

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.

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

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.