Standard File and Directory Set

Antora collects and processes content source files according to a set of hierarchical files and directories it expects to find at a content source root. This page introduces this hierarchy, the reserved directory and file names it employs, and the rules about which files get collected or ignored.

Hierarchy and reserved names

The set of files and directories, the reserved file and directory names, and their hierarchy that starts at a content source root—collectively referred to as Antora’s standard file and directory set — helps Antora determine which files to collect, the role of each file, how to classify each file, and which files to ignore. Example 1 shows the hierarchy Antora expects if all of the required and optional files and directories that make up the standard file and directory set are used.

In the following examples, 📒 repository represents the root of the file tree of a single reference, such as a branch, in a git repository.

Example 1. All required and optional files and directories of a standard file and directory set located at a repository root

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

1	The repository root and the content source root. By default, Antora assumes the content source root is at the root of a repository unless the `start_path` or `start_paths` key is assigned a value on a content source in your site’s playbook.
2	A component version descriptor file, named antora.yml (reserved file name), is required at each content source root. An antora.yml file indicates to Antora that the contents of a directory named modules should be collected and processed.
3	Required directory named modules (reserved directory name). A modules directory must be located at the same hierarchical level as an antora.yml file in a content source root. That is, the antora.yml file and modules directory are siblings. A modules directory must contain, at a minimum, either a ROOT module directory or a named module directory.
4	Optional ROOT module directory. Antora applies special behavior to the publishable resources in a ROOT module directory. ROOT is a reserved directory name and must be in all uppercase letters. A module directory must contain at least one family directory.
5	Optional attachments family directory (reserved directory name).
6	Optional examples family directory (reserved directory name).
7	Optional images family directory (reserved directory name).
8	Optional pages family directory (reserved directory name).
9	Optional partials family directory (reserved directory name).
10	Optional navigation file named nav.adoc.
11	Optional named module directory. You can create as many named module directories as you require. A module directory must contain at least one family directory.
12	Optional navigation file named nav.adoc.
13	Antora won’t process the files in this directory because it’s located outside the modules directory.

In Example 1, the content source root is located at the root of the repository. However, a content source root doesn’t have to be at the root of a repository. In Example 2, the content source root is located in a directory of the repository.

Example 2. All required and optional files and directories of a standard file and directory set located in a directory of a repository

📒 repository (1)
  📁 config (2)
  📂 docs (3)
    📄 antora.yml
    📂 modules
      📂 ROOT
        📁 attachments
        📁 examples
        📁 images
        📁 pages
        📁 partials
        📄 nav.adoc
      📂 named-module
        📁 pages
    📁 notes (4)
  📄 README.adoc (5)

1	Repository root
2	Antora ignores this directory because it isn’t specified as the content source root in the site’s playbook (for the purposes of this example).
3	The content source root as specified in the site’s playbook using the `start_path` or `start_paths` key (for the purposes of this example).
4	Antora won’t process the files in this directory because it’s located outside the modules directory.
5	Antora ignores this file because it isn’t in the content source root.

By default, Antora assumes the repository root and content source root are the same. If you’ve structured a repository where a content source root is located within a directory of the repository, you must specify the path to the directory using the start_path or start_paths key in your site’s playbook.

Many of the directories shown in Example 1 and Example 2 are optional. You only have to set up one module directory—and it can be a ROOT or named module directory—if that’s all you need. Also, you only need to set up the family directories in a module directory that best apply to the type and purpose of your source files. For example, if you aren’t inserting any images into the pages stored in a module directory, then you don’t need to create an images directory.

In the next section, you can see two content source examples that meet Antora’s minimum requirements of a valid standard file and directory set.

Minimum requirements

From a content source root, Antora must find:

An antora.yml file located at the content source root
A modules directory located at the same hierarchical level as an antora.yml file
At least one module directory in the modules directory
At least one family directory containing at least one source file in the module directory

Let’s look at two examples showing standard file and directory sets that meet the minimum requirements. The directory and file set in Example 3 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 3. Valid standard file and directory set containing a ROOT module directory

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

1	In this example, the content source root is at the root of the repository.
2	Component version descriptor file, with the valid filename antora.yml.
3	modules directory.
4	ROOT module directory.
5	pages family directory.
6	Source file of a page.

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

Example 4. 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)
            📄 image-source-file.ext (6)

1	Content source root.
2	Component version descriptor file, with the valid filename antora.yml.
3	modules directory.
4	A module directory named rz-interface.
5	images family directory.
6	Source file of an image.

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

Hidden and unpublished files

A hidden file is any file stored in Antora’s standard directory hierarchy that begins with a dot (.). Files that don’t have file extensions are also hidden, unless they’re stored in an examples directory or partials directory. Hidden files do not get added to Antora’s content catalog, and therefore aren’t assigned a resource ID, can’t be referenced, and aren’t published.

Example 5. Standard directory set containing hidden files

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 examples
        📄 .hidden-example-file.ext (1)
        📄 example-file (2)
      📂 pages
        📄 .hidden-page-file.adoc (3)
        📄 hidden-page-file (4)

1	Antora won’t load this example file into the content catalog because its filename begins with a dot (`.`).
2	Files stored in the examples directory aren’t required to have a file extension, therefore Antora will load this example file into the content catalog.
3	Antora won’t load this page file into the content catalog or publish it because its filename begins with a dot (`.`).
4	Antora won’t load this page file into the content catalog or publish it because it’s missing a file extension and page files must have a file extension.

Except when it’s typical for a file type to not have a file extension, such as Dockerfile, it’s a good practice to save example and partial source files with their valid file extensions. If you don’t save partial and example files with their file extensions, you may not be able to use Antora or Asciidoctor extensions that apply additional behavior to partial or example files.

An unpublished file is any file stored in Antora’s standard directory hierarchy that begins with an underscore (_). An unpublished file is added to the content catalog, assigned a resource ID (if applicable), and can be referenced. However, an unpublished file isn’t automatically published, even if it’s stored in the folder of a publishable family (that is, pages, images, or attachments).

Example 6. Standard directory set containing unpublished files

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 images
        📄 _unpublished-image-file.ext (1)
      📂 pages
        📄 _unpublished-page-file.adoc (2)

1	An image file with a filename that begins with an underscore (`_`) is loaded into the content catalog and can be referenced by an image macro. However, the image won’t be published automatically even though it’s stored in the folder of a publishable family.
2	A page file with a filename that begins with an underscore (`_`) is loaded into the content catalog and can be referenced by an include directive. However, the page can’t be referenced by an xref macro because it won’t be published as its own page even though it’s stored in the folder of a publishable family.