Page IDs and Cross References

What’s a page ID?

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.

What are the page ID coordinates?

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.

Diagram of an Antora page ID
version@

The first coordinate identifies the version of the component to which the target page belongs. The version is specified by the version key in the antora.yml file that defines the page’s component version. The version coordinate is directly followed by an at sign (@).

component:

The second coordinate identifies the name of the component to which the target page belongs. The component name is specified by the name key in the antora.yml file that defines the page’s component version. The component name is directly followed by one colon (:).

module:

The third coordinate identifies the name of the module to which the target page belongs. The module name is derived from the module directory where the page is stored. The module name is directly followed by one colon (:).

page.adoc

The fourth coordinate specifies the path relative to the pages family directory of the target page’s source file. If both the source page and the target page are located in the same subdirectory of the pages family directory, the path coordinate still needs to be specified relative to the pages directory. The filename must include the .adoc file extension.

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.

Keep in mind that the target of an xref is a page ID, not a URL. Therefore, the path portion must always be the complete path relative to the pages family directory.

What’s a cross reference?

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.

AsciiDoc xref macro

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.

Diagram of an AsciiDoc xref macro with an Antora page ID
xref:

The prefix of the AsciiDoc xref macro.

target page ID

The page ID coordinates of the target page relative to the current page. If the target page is in a subdirectory, the page coordinate of the page ID must include that subdirectory, even if the current page is located in the same directory. When the page ID contains the module coordinate, and the module name ends with the name of a built-in macro (e.g., monolink), you may have to escape that portion of the name by prefixing it with a backslash (e.g., mono\link).

#fragment

The element ID that links to a section, block, or inline location within the target page. A fragment is always optional. The fragment starts with the hash symbol (#). A page’s reftext (and navtitle) isn’t used as the default link text when a fragment is specified.

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

See xref:2.3@antora:ROOT:how-antora-works.adoc[].

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.

Why are page IDs important?

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.