Page Link Text

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 resource-id.adoc page in Antora’s own documentation.

See xref:resource-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.

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 resource ID of the target page is appended with a fragment (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.
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.