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.

Example 1. current-page.adoc
xref:target-page-filename.adoc[link text]

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.

Example 2. Standard directories assigned to the component version colorado 5.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 la-garita module.

Example 3. index.adoc (current page)
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.

Example 4. ranges.adoc (current page)
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.

Example 5. current-page.adoc
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 la-garita module.

Example 6. ranges.adoc (current page)
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.

Example 7. tour.adoc (current page)
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.

See xref:page-id.adoc[].

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.

See Page IDs and Cross References.

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. If navtitle isn’t set, then they use the page’s reftext value.

Learn more

To learn how to create xrefs to pages that belong to other components and component versions see Xref Pages in Other Components and Versions.