Page Cross References

To link between documentation pages, you’ll use the the AsciiDoc cross reference macro and a page ID. This syntax in also used to reference pages from your navigation files.

Reference by page ID

In Antora, a cross reference, commonly abbreviated xref, needs a page ID in order to link to another page in the site. The number of page ID coordinates you need to specify in the xref depends on the location of the current page in relation to the location of the destination page (i.e., the page you want to link to). The closer the two files are, the shorter the page ID.

In the next section, we’ll go over each part of the xref and page ID syntax.

The page ID is integral to Antora’s ability to publish a site to multiple environments and domains without you needing to modify your source content. If you want to learn more about the page ID, see Why are page IDs important?

Xref and page ID anatomy

Let’s dissect a cross reference with a fully-qualified page ID.

Page reference anatomy

Here’s what each part of the cross reference and page ID does:

xref:

The prefix of the AsciiDoc cross reference (xref) macro, which we’re using here to make a page reference.

version@

The first page ID coordinate is used to specify the version name of the destination component. This value is defined in the component descriptor file (antora.yml) in the branch of the component repository that hosts the destination file. When the version coordinate is filled, it must be directly followed by an at sign (@).

component-name:

The second coordinate specifies the name of the destination component. The component name is directly followed by one colon (:). This value is defined in the name key of the component descriptor in the branch of the component repository that hosts the destination file. If a component name is present, a module name must be specified after the :. Otherwise, this coordinate gets interpreted as the module name.

module-name:

The third coordinate specifies the name of the destination module. The module name is directly followed by one colon (:). If a component name is present, and the name of the module is ROOT, the module name position can be left empty in some cases. That’s why you see a component name followed by two colons (::) sometimes.

page.adoc

The fourth coordinate specifies the local path of the destination file relative to the module’s documents directory. This value may include one or more optional topic folders. The destination file name must have the .adoc file extension.

#fragment

An optional ID of a section or anchor point to link to in the destination page (i.e., deep link). This part is always optional.

[link text]

The text of the link that is displayed to the reader. This text must be entered inside a set of square brackets ([]) at the end of the macro. If the text is not specified, the raw target is used.

Scenario: In the same component and module

When the current page and the destination page are in the same module, you only need to enter the name of the destination file.

Link to a page in the same module
xref:error-handling.adoc[Error Handling]
Link to a page in a topic folder
xref:concept/index.adoc[Key Concepts]
Link to a page in the same module but in a different version
xref:3.3@error-handling.adoc#message-list[error messages]

Scenario: In the same component but a different module

When the current page and the destination page are in the same component but different modules, you’ll enter the name of the destination module and destination file.

Link to a page in another module
xref:get-started:implement-api.adoc[implement an API]
Link to a page in the ROOT module and in a topic folder
xref:ROOT:transports/c04-reference.adoc[C04 Transports]
Link to a page in the ROOT module and in a different version
The xref:3.4@ROOT:scopes/super-mass.adoc[super massive scope] splits atoms.

Scenario: In a different component

When the current page and the destination page are in different components, you’ll enter values for all of the coordinates. If a version is not specified, the implicit value is master@.

Link to a page in the ROOT module of a versioned component
How do I xref:2.0@default-ui::modify-template.adoc[modify a UI template]?
Link to a page in the ROOT module of a component that doesn’t have versions
xref:icons::index.adoc#intro[Introducing the Icon Project]
Link to a page in a module of a component that doesn’t have versions
xref:icons:web:modify-svg.adoc[Get started with the SVG assets]