Xref Macros and Page Links

To create a page link, you need to know:

how to structure and use the AsciiDoc xref macro,
how to assign the resource ID of a page to an AsciiDoc xref macro,
the resource ID of the page you’re linking to (the target page), and
the resource ID of the page where you want the link to be displayed (the current page).

AsciiDoc xref macro

An AsciiDoc xref macro is used to create a source-to-source cross reference from a resource to a publishable resource. The term cross reference, which is often abbreviated to xref, means to use the AsciiDoc xref macro to reference the source file of a publishable resource. The xref macro accepts an Antora resource ID specifying a publishable page, attachment, or, occasionally, an image, as a value. When Antora runs, an xref macro and its value are converted into a link to the target resource’s published URL.

Xref macro structure

Figure 1 shows the structure of an xref macro.

Diagram of an AsciiDoc xref macro with an Antora resource ID for a page

Figure 1. Xref macro structure for referencing a page

At a minimum, an xref macro consists of the macro’s prefix (xref:), the resource ID of the target page, and a set of square brackets ([]). The target page is the page source file that’s being referenced by the current page. The target page is referenced by assigning its resource ID to an xref macro in the content of the current page. The current page is the page source file containing the xref macro that references the target page. Each part of the xref macro shown in Figure 1 is described in more detail below.

xref:: An xref macro begins with the macro’s name, xref, followed by a single colon (:).
resource ID of target page: The xref macro accepts the resource ID of a page as its value. The value is entered directly after the colon that follows the macro’s name (xref:). How many of the target page’s resource ID coordinates you need to specify depends on the component version and module of the target page in relation to the current page. The page$ family coordinate isn’t required in the resource ID when the target resource is a page. Also, remember that the file coordinate of a target page is calculated from the pages family directory.

#fragment: A fragment is an element ID that links to a section, block, or inline location within the target page. Fragments are also referred to as deep links. A fragment is optional. The fragment starts with the hash symbol (#) and is entered directly after the resource ID of the target page. A target page’s reference text, whether assigned by default or using the reftext attribute, isn’t used as link text when a fragment is specified.

[link text]: The xref macro is completed with a set of square brackets ([]) at the end of the target page’s resource ID, or, if specified, at the end of the fragment. You can enter optional text between these brackets or leave them empty. When Antora converts the xref macro and its value into a link, the text entered between the square brackets is displayed in the current page when it’s published to your site. If no link text is specified between the macro’s square brackets, and the value of the xref macro doesn’t contain a fragment, then the target page’s default reference text or text assigned to the reftext attribute is displayed in the current page when it’s published. If a fragment is appended to the resource ID of the target page and no link text is entered between the brackets, then the URL of the published target page is displayed.

The next section explains how to create a cross reference step-by-step.

Make a link with the xref macro

Let’s break down the xref macro and resource ID coordinates you need to create a cross reference to a page (the target page) from a page that you’re currently editing (the current page).

In your IDE or text editor, open the page where you want to create a cross reference. For this step and the subsequent steps, let’s assume you’ve opened the file satellites.adoc. satellites.adoc is the current page.
Example 1. satellites.adoc (current page)
```
=== Console options

See the
```
In the current page, select the location in the content flow where you want the link to the target page to be displayed. Enter the name of the xref macro followed by one colon, xref:.
Example 2. satellites.adoc (current page)
```
=== Console options

See the xref:
```
Assign the resource ID of the target page to the xref macro. In Example 3, let’s use modes.adoc as the target page and assume that it and the current page, satellites.adoc, belong to the same component version and module. Therefore, only the file coordinate of the target page needs to be specified.
Example 3. satellites.adoc (current page)
=== Console options See the xref:modes.adoc
The file coordinate for the modes.adoc page is modes.adoc. The target page’s file coordinate consists solely of its filename and file extension because it’s stored at the root of the pages directory.

The resource ID for modes.adoc doesn’t include the page$ family coordinate. The xref macro assumes the family coordinate is page$ when it isn’t specified.
Directly after the resource ID of the target page, enter an opening square bracket ([), then a closing square bracket (]), followed by any subsequent content.
Example 4. satellites.adoc (current page)
=== Console options See the xref:modes.adoc[] for more options.
We didn’t enter any text between the macro’s square brackets because we want the target page’s reference text to be used as the link text. When Antora converts the xref macro and target page’s resource ID, it will automatically populate the link text with the target page’s default reference text or text assigned to the reftext attribute.

That’s it! You’ve created a cross reference to the target page (modes.adoc) from the current page (satellites.adoc) using the AsciiDoc xref macro.

Learn more

Create Page Links shows how to create xrefs to pages when the target page is stored in a subdirectory or it belongs to another module, component, or version.

The xref macro can also be used to create links to attachments and images.