Customize reftext and navtitle

The reftext and navtitle attributes are automatically set and assigned default values when Antora runs. You can customize the values of these attributes by setting them in the header of a page.

reftext attribute

A target page’s reftext value is used as the link text in an xref that originates from a page or resource file. By default, Antora assigns a page’s title to the reftext attribute at runtime. In Example 1, let’s reference the install-prerequisites.adoc file and leave the link text field empty.

Example 1. current-page.adoc
Make sure you xref:install-prerequisites.adoc[].

Now, let’s look at the header of the install-prerequisites.adoc file.

Example 2. install-prerequisites.adoc
= Installing and Testing Silver Leaf's Prerequisites

Here are the prerequisites:

Notice in Example 2 that reftext isn’t set in the page’s header. That means its title, Installing and Testing Silver Leaf’s Prerequisites, will be automatically assigned to reftext at runtime and used in Example 1 as the xref’s link text.

If you don’t want a page’s title to be used as its default reftext, assign the attribute a custom value with an attribute entry. Example 3 shows the reftext attribute being assigned a custom value.

Example 3. Assign a custom reftext value
= Installing and Testing Silver Leaf's Prerequisites
:reftext: Install Silver Leaf's Prerequisites

Here are the prerequisites:

When the site is generated, the value of reftext, Install Silver Leaf’s Prerequisites, will be used in Example 1 as the xref’s link text. It will also be used as the page’s navtitle value.

When the resource ID of the target page is appended with a fragment, the link text isn’t automatically populated. You’ll need to specify the xref’s link text in such cases.

A target page’s navtitle value is used as the link text in an xref that originates from a navigation file. By default, Antora assigns the value of a page’s reftext attribute to navtitle. A page’s reftext is often automatically assigned the page’s title.

In Example 4, let’s reference the get-started.adoc file from a navigation file, and leave the link text field empty.

Example 4. nav.adoc
* xref:index.adoc[]
* xref:get-started.adoc[]

Now, let’s look at the header of the get-started.adoc file in Example 5.

Example 5. get-started.adoc
= Get Started with Silver Leaf

Let's get started!

Notice that neither reftext nor navtitle are set in it’s header. That means the page’s title, Get Started with Silver Leaf, will be automatically assigned to reftext, and therefore, to navtitle, and used to populate the xref link text in the navigation file.

If you don’t want a page’s default or custom reftext value to be assigned as the default navtitle, assign the attribute a custom value with an attribute entry. Example 6 shows the navtitle attribute being assigned a custom value.

Example 6. Assign a custom navtitle value
= Get Started with Silver Leaf
:navtitle: Getting Started

Let's get started!

When the site is generated, the value of navtitle, Getting Started, will populate the xref link text in the navigation file.

When the resource ID of the target page is appended with a fragment (aka a deep link) and no link text is specified between the square brackets, like xref:page.adoc#fragment[], the link text isn’t automatically populated. You’ll need to specify the link text in the xref macro when using a fragment.