Standard File and Directory Set

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 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.

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.

From a content source root, Antora must find:

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.

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

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

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.

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).