Page Xrefs and Link Text in Navigation Files

Page xrefs

Cross references to pages in a navigation list are constructed using the AsciiDoc xref macro and the resource ID of a page.

The xrefs in a navigation file’s list most often target pages that belong to the same module as the navigation file. In these cases, the resource IDs don’t require the version, component, or module coordinates. However, regardless of what component version a navigation file belongs to, you can still link to any page in the site from any navigation list, whether they belong to a different modules or components.

Example 1. nav.adoc

* xref:filename.adoc[Optional link text] (1)
* xref:module:filename.adoc[] (2)
* xref:version@component:module:filename.adoc[] (3)

1	Xref targeting a page in the same module. The xref also specifies link text.
2	Page in the same component version, but a different module.
3	Page in another docs component.

Xrefs in navigation files can use the target page’s default navigation link text or have link text specified inside the macro’s square brackets ([]). The link text is displayed in the component version’s page menu. When a visitor clicks on the link text, they’re routed to the target page specified by the resource ID in the xref. The link text, regardless of whether it’s the default link text or specified in the xref, is also displayed in the breadcrumbs at the top of the target page.

Use the default navigation link text

Xrefs in a navigation file don’t need to specify link text.

Example 2. nav.adoc

* xref:get-started.adoc[] (1)

1	Xref that doesn’t have any link text specified inside the macro’s square brackets (`[]`).

Antora uses the value assigned to the optional navtitle attribute in the target page when the link text is unspecified. When navtitle isn’t set in the target page’s header, Antora automatically assigns it the value of the page’s reference text, which may either be the target page’s default reference text or text assigned to the reftext attribute.

Antora doesn’t populate an xref’s link text when a fragment is appended to the resource ID of a page. In such cases, you still need to explicitly specify the link text.

Specify link text in an xref

You can enter link text directly in the xref macro and override the default link text supplied by the target page.

Example 3. nav.adoc

.The Special Project
* xref:index.adoc[What's Silver Leaf] (1)
** xref:ROOT:get-started.adoc#prereqs[Installation Prerequisites] (2)
** xref:team::contributing.adoc[] (3)

.Support
* xref:help.adoc[*Troubleshooting*] (4)

1	Enter the link text between the xref macro’s square brackets (`[]`).
2	Xrefs where the target page’s resource ID is appended with a fragment should specify link text.
3	This xref will use the target page’s default navigation link text.
4	Specified link text can be marked up with inline formatting syntax.

The link text specified in the xref macros will be displayed in the component version page menu.