Xref Pages in a Component Version
The majority of your cross references will probably be between pages that belong to the same module or to the same component version.
Xref pages that belong to the same module
Only the page coordinate of the target page needs to be entered in the page ID when the current page and target page belong to the same component version and module.
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.
Xref pages in a topic folder
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.
Xref pages from other modules
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].
Use the target page’s default link text
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
Xrefs in a navigation file behave the same way with one additional feature.
Navigation files use the navtitle value to populate missing link text.
To learn how to create xrefs to pages that belong to other components and component versions see Xref Pages in Other Components and Versions.