Standard File and Directory Set

Antora collects and processes content source files that are organized in a standard hierarchy under a content source root. This hierarchy (i.e., directory structure) and its reserved names helps Antora understand which files to collect, the role of each of those files and how they should be classified, and which files to ignore. The required antora.yml file and the optional navigation file(s) also give Antora information about how to classify the files and what metadata to apply to them.

This page introduces this hierarchy, the reserved names it employs, and the rules about which files get collected or ignored.

Hierarchy and reserved names

Example 1 shows the hierarchy of the standard file and directory set if all of the possible standard directories are used. The content source root in Example 1 is at the root of the repository. However, a content source root can also be a subdirectory in the repository, which you can see in Example 3.

Example 1. All required and optional standard files and directories

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📂 attachments (5)
      📂 examples (6)
      📂 images (7)
      📂 pages (8)
      📂 partials (9)
      📄 nav.adoc (10)
    📂 a-named-module (11)
      📂 pages

1	Content source root.
2	Required component version descriptor file. This file indicates to Antora that the contents of the modules directory should be collected and processed.
3	Required modules directory. This directory contains one or more module directories.
4	Optional ROOT module directory.
5	Optional attachments family directory.
6	Optional examples family directory.
7	Optional images family directory.
8	Optional pages family directory.
9	Optional partials family directory.
10	Optional navigation file named nav.adoc.
11	Optional named module directory, which can have any of the same folders shown in the ROOT module.

As you can see in the descriptions above, navigation files and many of the directories are optional. For instance, if you aren’t inserting any images into the content stored in a module directory, then you don’t need to create an images directory. You can see two examples of simple standard file and directory sets in the next section.

Minimum requirements

From a content source root, Antora must find:

An antora.yml file
A modules directory
At least one module directory
At least one family directory containing at least one source file

The antora.yml file and directories must also be organized in the standard hierarchy from the content source root.

Let’s look at two examples of standard file and directory sets that meet the minimum requirements. The directory and file set in Example 2 is valid because it contains the required antora.yml and modules directory at the content source root. The modules directory contains one module directory, in this case the special ROOT module directory. In turn, the ROOT module directory contains a family directory that contains one source file.

Example 2. Valid standard file and directory set containing a ROOT module directory

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📂 pages (5)
        📄 a-source-file.adoc (6)

1	Content source root
2	Required antora.yml file
3	Required modules directory
4	ROOT module directory
5	pages family directory
6	Source file for a page

In Example 3, the content source root is located at the directory ops-training.

Example 3. Valid standard file and directory set containing a named module directory

📒 repository
  📂 courses
    📂 ops-training (1)
      📄 antora.yml (2)
      📂 modules (3)
        📂 rz-interface (4)
          📂 images (5)
            📄 an-image-file.png (6)

1	Content source root
2	Required component version descriptor file
3	Required modules directory
4	A module directory named rz-interface
5	images family directory
6	Source file for an image

The standard directory and file set in Example 3 is also valid.

Hidden and unpublished files

Antora ignores any files stored in hierarchy that begin with a dot (.) or which don’t have a file extension. These hidden files do not get added to Antora’s content catalog and thus cannot be referenced or published. If the filename begins with an underscore (_), it’s added to the content catalog, but isn’t automatically published, even if it’s stored in a folder of a publishable family (like pages).

Example 4. Standard directory set containing hidden and unpublished files

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 pages
        📄 .a-hidden-file.adoc (1)
        📄 a-hidden-file (2)
        📄 _an-unpublished-file.adoc (3)

1	Antora won’t load this file into the content catalog or publish it because its filename begins with a dot (`.`).
2	Antora won’t load this file into the content catalog or publish it because it’s missing a file extension.
3	A filename that begins with an underscore (`_`) is loaded into the content catalog and can be referenced by an include directive, but it won’t be published automatically even when stored in the folder of a publishable family.

Support for loading files without extensions into the content catalog and publishing them is being considered for a future Antora version. See issue #368.