Attachments

Attachments are downloadable resources, such as PDFs or the ZIP archives of sample projects, that are stored in an attachments family directory. You create links to attachments using the xref macro. Although not as common, an example file can be reclassified as an attachment to make it downloadable as well. Unlike images, attachments cannot be inserted directly into a page.

AsciiDoc xref macro for attachments

An attachment can be cross referenced from pages, other resources, and navigation files using an AsciiDoc xref macro and the attachment’s resource ID.

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

Example 1. Xref macro structure for referencing an attachment

xref:version@component:module:attachment$file-coordinate-of-attachment.ext[optional link text]

At a minimum, an xref macro consists of the macro’s prefix (xref:), the resource ID of the target attachment, and a set of square brackets ([]). The target attachment is the attachment source file that’s being referenced by the current page. The target attachment 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 attachment.

When referencing an attachment, the xref macro is structured and behaves much like when it’s assigned the resource ID of a page, with three differences:

The resource ID of an attachment must specify the attachment$ family coordinate when an attachment is assigned to an xref macro, otherwise Antora will assume the resource ID is that of a page at runtime.
A fragment (element ID) can’t be appended to the end of the attachment’s resource ID.
Attachments don’t have default reference text. If link text isn’t specified in the xref macro, the target of the xref is displayed as the link text.

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

Make a link to an attachment

Let’s break down the xref macro and resource ID coordinates you need to create a cross reference to an attachment (the target attachment) 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 to an attachment. For this step and the subsequent steps, let’s assume you’ve opened the source file for a page named satellites.adoc. satellites.adoc is the current page.
Example 2. satellites.adoc (current page)
```
= System Satellites

The group maintains five satellites.
```
Select the place in the content flow of the current page where you want the link to the target attachment to be displayed. Enter the name of the xref macro followed by one colon, xref:.
Example 3. satellites.adoc (current page)
```
The group maintains five satellites.
See the xref:
```
Let’s reference the source file of an attachment with the filename flight-patterns.pdf. Both flight-patterns.pdf and satellites.adoc belong to the same component version and module. Therefore, only the attachment$ family coordinate and file coordinate of the target attachment needs to be assigned to the xref macro in Example 4. Directly after the macro’s prefix, enter the resource ID of the target attachment.
Example 4. satellites.adoc (current page)
The group maintains five satellites. See the xref:attachment$flight-patterns.pdf
The file coordinate for flight-patterns.pdf consists solely of its filename and file extension because it’s stored at the root of the attachments directory. The target attachment’s file coordinate is always calculated from the root of the attachments family directory where the attachment is stored. If the target attachment is stored in a subdirectory of an attachments directory, its file coordinate must specify the attachments-relative directory path, filename, and file extension. (See Example 8 for an example.)
Directly after the resource ID of the target attachment, enter an opening square bracket ([), then a closing square bracket (]).
Example 5. satellites.adoc (current page)
```
The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf[]
```
Let’s add some link text to the xref macro because, unlike pages, attachments don’t have default reference text. Between the macro’s square brackets, specify the text you want displayed as a link to the target attachment when the current page is published.
Example 6. satellites.adoc (current page)
The group maintains five satellites. See the xref:attachment$flight-patterns.pdf[flight pattern schedule]
Link text is optional. See Link text for attachments for more information.
After the closing square bracket (]) of the xref macro, continue entering your content.
Example 7. satellites.adoc (current page)
```
The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf[flight pattern schedule] for more details.
```

That’s it! You’ve created a cross reference to the target attachment, flight-patterns.pdf, from the current page, satellites.adoc, using the AsciiDoc xref macro.

While the previous steps use a target attachment and current page that belong to the same component version and module, you can reference any attachment in your site, regardless of the component version and module it belongs to, from any page. You’ll need to specify additional resource ID coordinates when the target attachment and current page don’t belong to the same module or component version.

Example 8. Resource ID patterns for a target attachment in relation to a current page

xref:attachment$target-attachment-filename.ext[link text] (1)

xref:attachment$path/to/target-attachment-filename.ext[link text] (2)

xref:attachment$./target-attachment-filename.ext[link text] (3)

xref:module:attachment$file-coordinate-of-attachment.ext[link text] (4)

xref:version@component:module:attachment$file-coordinate-of-attachment.ext[link text] (5)

xref:component:module:attachment$file-coordinate-of-attachment.ext[link text] (6)

xref:version@module:attachment$file-coordinate-of-attachment.ext[link text] (7)

xref:version@attachment$file-coordinate-of-attachment.ext[link text] (8)

1	Assign the `attachment$` family coordinate and file coordinate of the target attachment to the xref macro when the target attachment and current page belong to the same component version and module. The target attachment’s file coordinate is its filename and file extension when the target attachment is stored at the root of an attachments family directory.
2	If the target attachment is stored in a subdirectory of an attachments directory, the target attachment’s file coordinate must specify its attachments-relative directory path, filename, and file extension.
3	The file coordinate of the target attachment can be abbreviated with the relative path token (`./`) when the target attachment and current page are stored in subdirectories with parallel family-relative directory paths. This is an advanced use case.
4	Assign the module, `attachment$`, and file coordinates of the target attachment to the xref macro when the target attachment and current page don’t belong to the same module, but they do belong to the same component version.
5	Assign the version, component, module, `attachment$`, and file coordinates of the target attachment to the xref macro when the target attachment and current page don’t belong to the same component version.
6	If the version coordinate isn’t specified, Antora uses the latest version of the target attachment’s component to complete the resource ID at runtime. This behavior only applies when the target attachment and current page don’t belong to the same component version.
7	Assign the version, module, `attachment$`, and file coordinates of the target attachment to the xref macro when the target attachment doesn’t belong to the same version and module as the current page, but it does belong to the same component as the current page.
8	Assign the version, `attachment$`, and file coordinates of the target attachment to the xref macro when the target attachment doesn’t belong to the same version as the current page, but it does belong to the same component and module as the current page.

Attachment links and page links share many similarities. See Create Page Links for more examples that show how to construct the resource ID of the target resource when it doesn’t belong to the same module, component version, or version as the current page. Just remember to always add the attachment$ family coordinate to the target attachment’s resource ID when you assign it to an xref macro.

Link text for attachments

You can specify link text between the square brackets of an AsciiDoc xref macro, or you can leave the square brackets of the xref macro empty. Example 9 shows an xref macro that’s assigned the resource ID of an attachment. No link text has been specified between the xref macro’s square brackets.

Example 9. Xref macro without specified link text

Download xref:attachment$practice-project.zip[] to try it out!

Because the xref macro in Example 9 isn’t assigned link text, Antora will display the xref target as the link text.

Download attachment$practice-project.zip to try it out!

Unlike pages, attachments don’t have default reference text, so it’s always good to specify link text to ensure a good reader experience.

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

Example 10. Xref macro with specified link text

Download xref:attachment$practice-project.zip[the sample project] to try it out!

When link text is specified in the xref macro, Antora displays the specified content as the link to the attachment in the published page.

Include an attachment

Instead of linking to an attachment, you can include it into an AsciiDoc page or partial using the include directive. The only restriction is that the file must be a text file. Storing a text file as an attachment allows it to be included while still being downloadable.

Here’s the full syntax that shows how to include the text of an attachment into a page.

include::version@component:module:attachment$name-of-file.ext[optional attributes]

The attachment$ segment tells Antora to look for the file in the attachments folder. If the attachment lives in the same component version and module as the page, the target can start with the attachment$ segment.

include::attachment$name-of-file.ext[optional attributes]

You can use the same attachment in both an xref macro and an include directive.

Learn more

You can also create links to attachments in navigation files and from image macros.