Page Cross References
To link between documentation pages, you’ll use the the AsciiDoc cross reference macro and a page ID. This syntax is also used to reference pages from your navigation files.
Reference by page ID
In Antora, a cross reference, commonly abbreviated to 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.
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.
xref:error-handling.adoc[Error Handling]xref:concept/index.adoc[Key Concepts]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.
xref:get-started:implement-api.adoc[implement an API]xref:ROOT:transports/c04-reference.adoc[C04 Transports]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 must specify the target component.
If a version is not specified, the implicit value is the latest version.
If the module is not specified, the implicit value is ROOT.
How do I xref:2.0@default-ui::modify-template.adoc[modify a UI template]?xref:icons::index.adoc#intro[Introducing the Icon Project]xref:icons:web:modify-svg.adoc[Get started with the SVG assets]