Xref Pages in a Component Version
For context, let’s use the pages that belong to the component version
colorado 5.2 as the basis for the examples on this page.
The component version’s source files are stored in the set of standard directories listed in Example 2.
📒 repository 📄 antora.yml 📂 modules 📂 get-started 📂 pages 📄 tour.adoc 📂 la-garita 📂 pages 📄 cochetopa-pass.adoc 📄 index.adoc 📂 ROOT 📂 pages 📄 index.adoc 📄 ranges.adoc 📂 terms 📄 faqs.adoc
The simplest xref is when the target and current pages belong to the same module.
Example 3 shows an xref in the page index.adoc (current page) that links to the cochetopa-pass.adoc page (target page).
Both pages belong to the
There are xref:cochetopa-pass.adoc[historic passes] in the range.
When the xref in Example 3 is converted by Antora, it will become a link to the published site page at https://base-url.com/colorado/5.2/la-garita/cochetopa-pass.html.
If the target page is nested in a topic folder, include the pages family directory relative path in the page coordinate.
In Example 4, an xref in the page ranges.adoc (current page) links to the faqs.adoc page (target page).
Both pages belong to the
ROOT module, and faqs.adoc is nested in the topic folder terms.
See the xref:terms/faqs.adoc[FAQs].
The xref in Example 4 will become a link to the published site page at https://base-url.com/colorado/5.2/terms/faqs.html when the site is generated.
The target page’s module coordinate and page coordinate are required when the current and target pages belong to different modules.
xref:module:target-page-filename.adoc[optional link text]
The following examples use the pages that belong to the component version colorado 5.2.
As seen in Example 6, let’s create an xref in the page ranges.adoc (current page) that links to cochetopa-pass.adoc (target page).
The ranges.adoc page belongs to the
ROOT module, while cochetopa-pass.adoc belongs to the
Only xref:la-garita:cochetopa-pass.adoc[one pass is open] in the winter.
When published to a site, the current page will contain a link to the published target page’s URL https://base-url.com/colorado/5.2/la-garita/cochetopa-pass.html.
If the target page is nested in a topic folder, include the pages family directory relative path as part of the page coordinate.
In Example 7, an xref in the page tour.adoc (current page) links to the faqs.adoc page (target page).
The page tour.adoc belongs to the
get-started module, and faqs.adoc belongs to the
ROOT module and is nested in the topic folder terms.
See the xref:ROOT:terms/faqs.adoc[FAQs].
When an xref doesn’t specify any link text, Antora uses the target page’s
reftext value as the link text.
Let’s create an xref to the page-id.adoc page in Antora’s own documentation.
Notice the xref doesn’t have any link text specified. As you can see in the example output below, Antora automatically fills in the link text using the title of the target page.
If you click on the link, you’ll see that the clickable text and the title of the target page are the same.
A page’s title is assigned to the built-in AsciiDoc
reftext attribute by default.
You can also assign a custom value to the reftext attribute.
When the target includes a fragment (aka a deep link) like
xref:page.adoc#fragment[…], the link text (
…) isn’t automatically populated.
You’ll need to specify the xref’s link text in this case.
Xrefs in a navigation file behave the same way with one additional feature.
Navigation files use the navtitle value to populate missing link text.
navtitle isn’t set, then they use the page’s
To learn how to create xrefs to pages that belong to other components and component versions see Xref Pages in Other Components and Versions.