Partials Directory and Files

Partials family directory

A module directory can contain a family directory named partials.

📂 modules
  📂 ROOT (1)
    📁 images
    📁 pages
    📂 partials (2)
      📄 partial-source-file.adoc (3)
    📄 nav.adoc
  📂 named-module (4)
    📁 pages
    📂 partials (5)
      📄 partial-source-file.adoc
      📂 subdirectory-of-partials (6)
        📄 partial-source-file.adoc
1 A ROOT module directory.
2 A partials family directory. Antora classifies source files stored in a partials directory as partials.
3 A partial file marked up with the AsciiDoc syntax and saved with the .adoc file extension.
4 A named module directory.
5 A partials family directory.
6 A subdirectory in partials. Source files stored in subdirectories of a partials directory are classified as partials.

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

Partial files

Antora classifies the source files stored in a partials directory as partial files, or partials for short. Partials are usually AsciiDoc files that contain content snippets, such as common descriptions or terminology, that are inserted into one or more pages or partials. However, Antora doesn’t require partials to be AsciiDoc files.

When saving a new partial file, keep the following filename requirements and recommendations in mind:

  • Spaces aren’t recommended in partial filenames. While the AsciiDoc include directive does accept spaces in the target, some editing tools may not support it and is thus not recommended.

  • Uppercase letters and spaces aren’t recommended in partial filenames. Some file systems aren’t case sensitive. Therefore, file conflicts could occur when using git depending on the file system a writer is using.

  • Save a partial file with the .adoc extension when it’s an AsciiDoc file, otherwise use the valid file extension for the file type. You should only save a partial without a file extension when it’s common industry practice for that specific file type to not have an extension. Not using the correct file extension when saving a partial file may limit your ability to apply some Antora extensions or upgrade to future capabilities.

A partial isn’t required to have a file extension. Unlike a publishable resource that’s treated as a hidden file if it’s missing a file extension, Antora will load a partial that doesn’t have a file extension into its content catalog and assign the partial a resource ID for referencing.

Antora doesn’t publish partial files as individual site pages. A partial must be referenced by an include directive from a page, or resource that’s eventually included in a page, for the partial’s content to be published.

Except when it’s typical for a file type to not have a file extension, it’s a good practice to save your partial source files with their valid file extensions.

Learn more