Attachment Xrefs in Navigation Files

To reference an attachment, use the 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. nav.adoc
* xref:attachment$filename.pdf[Our Brochure] (1)
* xref:version@component:module:attachment$filename.epub[Our Book] (2)
1 Xref targeting an attachment that belongs to the same component version and module as the navigation file.
2 Xref where the resource ID specifies an attachment that is in a different component version than the navigation file.

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 component version’s page menu.

Example 2. nav.adoc
* xref:attachment$sample-project.zip[]

The computed URL resulting from Example 2, +https://docs.example.com/component/version/module/_attachments/sample-project.zip+, would display as a link in the page menu.

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

Example 3. nav.adoc
* xref:attachment$sample-project.zip[Practice Project]

Using Example 3, Antora would display the text Practice Project as a link in the page menu. When a visitor clicks on the link, their browser will download or display the published attachment depending on the file format of the attachment and their browser’s settings.