Attachments Directory and Files

Attachments family directory

A module directory can contain a family directory named attachments.

📂 modules
  📂 ROOT (1)
    📂 attachments (2)
      📄 attachment-source-file.ext (3)
    📁 images
    📁 pages
    📄 nav.adoc

1	A ROOT module directory.
2	An attachments family directory. Antora classifies source files stored in an attachments directory as attachments.
3	An attachment source file.

The attachments directory is optional. Antora applies preset behavior to the files stored in an attachments directory when it generates a site.

Attachment files

An attachment is typically a file a site visitor views or downloads using their browser, such as a PDF or the ZIP archive of a sample project.

At runtime, Antora automatically:

Loads each file from an attachments directory into the Antora content catalog, except for files marked as hidden or missing a file extension
Assigns each loaded attachment file to the attachment family
Assigns each loaded attachment a unique resource ID for source-to-source referencing
Publishes each loaded attachment file as an individual page in a site, except for files marked as unpublished

Using an attachment’s resource ID, you can cross reference an attachment from other pages, resources, or navigation files in your site. Antora uses the family directory, attachments-relative directory path (if present), filename, and file extension of the attachment when building the URL of an attachment.

Binaries and other large files

If your content includes large attachment files, such as sample project binaries, libraries, or PDFs, we don’t recommend storing them in a regular git repository. Instead, host them in a binary repository such as Bintray or S3, or use git LFS (Large File Storage).

Assets

A module directory can also contain a directory named assets. This is an alternate location, recognized by Antora, where the attachments and images family directories can be placed.

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 assets
        📂 attachments
          📄 attachment-source-file.ext
        📂 images
          📄 image-source-file.ext
      📁 pages
      📄 nav.adoc

You don’t need to set the path to these predefined directories in the header of your pages. This is managed automatically by Antora.

Learn more

Attachments