Attachments are resources, such as PDFs or the ZIP archives of sample projects. Attachment files are stored in an attachments family directory.

An attachment can be cross referenced from pages, other resources, and navigation files using an AsciiDoc xref macro and the resource ID of the attachment. The attachment$ family coordinate must be specified in the attachment’s resource ID.

Example 1 shows the structure of an AsciiDoc xref macro with an attachment’s fully qualified resource ID.

Example 1. Xref and attachment resource ID syntax
xref:version@component:module:attachment$filename.ext[link text]

How many coordinates of the attachment’s resource ID you need to specify in the target of the xref macro depends on the component version and module of the current page in relation to the attachment.

Xref an attachment from a page

Let’s break down the xref macro and resource ID coordinates you need to create a link to an attachment from a page. The following steps assume that the target attachment and current page belong to the same component version and module. Therefore, the resource ID of the target attachment only requires the family coordinate, attachment$, and family-relative path of the attachment file.

  1. In the flow of your content, enter the name of the macro followed by one colon, xref:.

    See the xref:
  2. Enter the resource ID of the target attachment file. The resource ID must specify the attachment$ family coordinate.

    See the xref:attachment$filename.ext
  3. Directly after the attachment’s file extension, enter an opening square bracket ([), followed by optional link text, and then a closing square bracket (]).

    See the xref:attachment$filename.ext[optional link text] for more options.

If you don’t specify link text in an xref macro that targets an attachment, Antora displays the URL of the attachment as the link in the published page.

Example 2. Attachment xref with no link text
Download xref:attachment$[] to try it out!

The result of Example 2, would be display as shown below.

Download to try it out!

You can specify link text by entering it between the square brackets of the xref macro.

Example 3. Attachment xref with link text
Download xref:attachment$[The Sample Project] to try it out!

Xrefs to attachments can also be created in navigation files, image macros, and partials.