Link to an Attachment

On this page, you’ll learn:

  • How to link to a file stored in a documentation component’s attachments directory.

An attachment is a resource that you want your user to download, such as a PDF or a sample project ZIP archive. To insert a link to an attachment for download, use the AsciiDoc link macro (link:[]).

Attachment link syntax
link:{attachmentsdir}/example.raml[Download the RAML example] and run it.

Let’s break this down. You start with the link macro prefix, link:. Next is the target. Start the target with the {attachmentsdir} attribute reference to tell Antora where to look for the file. Then put the relative path of the attachment file after that. Finally, end with the text of the link (as the reader will see it) between a pair of square brackets ([]).

You don’t need to set the path to the attachments directory in the header of your file. This is managed automatically by Antora. When viewing the file in a preview tool, the path is managed by the adjacent _attributes.adoc file.

A module’s attachment files should be saved in its attachments folder. Links to attachments can also be added to the site navigation.