Page IDs and Cross References

In order for a page to be referenced, that page must have an identifier—​a page ID. An Antora page ID is a unique and reliable set of identifying coordinates, organized in a standard sequence, that are constructed from the properties assigned to each page’s source file. A page ID is most often used as a target in an AsciiDoc xref macro, but it can also be assigned to certain attributes and keys.

Antora constructs a page ID for a page source file from the key-value pairs specified in a component version descriptor and the standard directory set. Using this information, each page can be cross referenced using a sequence of page ID coordinates.

The coordinates are organized into the standard sequence shown below.

A page ID is used in an AsciiDoc xref macro to create a link from one page to another page. They’re also used to create the links in a component version’s navigation files.

A cross reference indicates that an element in a page, such as a term or concept, is related to information on another page. Cross reference is often abbreviated to xref.

A cross reference is created using the AsciiDoc xref macro and the page ID of the target page. The target page is the page the xref will link the site visitor to. The current page is the page containing the xref that links to the target page. When a visitor clicks on an xref in the current page, that is, the page they’re currently viewing, they’ll be redirected to the target page.

An AsciiDoc xref macro needs to be supplied with a valid page ID in order to create a link to the target page when the site is generated. How many page ID coordinates you need to specify depends on the component version and module of the current page in relation to the target page.

First, let’s review the AsciiDoc xref macro syntax.

Here’s how an xref macro with a fully qualified page ID looks in practice:

Specifying the version, component name, and even module every time seems verbose, right? Don’t worry, the more related the current and target pages are, the less coordinates you need to enter in the page ID. For instance, if the target and current pages belong to the same component version and module, you only need to specify the page coordinate of the target page.

Xref Pages in a Component Version has several examples showing how to create xrefs to pages that belong to the same module or component version. For xref examples where the target and current pages belong to different components or different versions of the same component, see Xref Pages in Other Components and Versions.

They’re not coupled to a published URL because they’re a source-to-source reference. Notice the page coordinate ends with .adoc, the file extension of an AsciiDoc source file. Regardless of whether you’re deploying your site locally, to a staging or production environment, or you change URL strategies, the page ID always remains the same. The xref locks on to the target page and produces a URL that points to it wherever it gets published.

They’re minimally coupled to the filesystem by using an identifier based on the Antora’s virtual component version classification system.

They’ve eliminated the relative path (../../) problem by specifying the page as a pages-relative path. The path always starts from a module’s pages directory, even when the referencing page is located inside a topic folder.

This human-friendly referencing system saves you from having to do computations in your head while writing. You just specify the coordinates of the page you want to reference. There’s no need to worry about the source file’s physical location on disk or its published URL. All you need to know are the names of your components, versions, modules, and pages so you can fill in this information.