Modules, Families, and Subdirectories

What is a module?

A documentation component is composed of one or more modules. A module is a discrete bundle of content that is usually related by concept, stage, feature, or workflow. A module can contain full page text files, reusable text and example snippets, images, and other source materials that are organized into families. The content associated with a module is stored in a module directory and its files are sorted into family subdirectories.

Module directory names and structure

A module directory represents a module in a documentation component. A component’s module directories must reside in the modules directory. Figure 1 illustrates a documentation component with three module directories. You can create as many module directories as you require.

Directory structure of a component containing three modules. The ROOT module contains all of the possible family subdirectories.
Figure 1. Directory structure of a documentation component containing two named modules and a ROOT module.

Figure 1 contains two directories that represent named modules, a-named-module and another-named-module. You choose the directory name of a named module. This directory name is then used as the module coordinate in a resource ID, so it can’t contain spaces. If your team often references pages, examples, images, or partials across modules, they’ll have to type the target file’s module coordinate in a resource ID, so don’t make the directory name hard to remember or extremely long.

In addition to being the module coordinate, the directory name of a module, with the exception of the special ROOT directory, also appears in the site’s output path. See URLs for named module pages to learn more.

Inside of a module directory, you can create one or more family subdirectories. Antora recognizes family subdirectories named attachments, examples, images, pages, and partials. In Figure 1, the a-named-module directory contains two family subdirectories while the ROOT directory just happens to contain all five possible family subdirectories.

Let’s examine the role of the ROOT module in more depth.

ROOT module

The ROOT module typically contains the content that’s directly associated with the documentation component itself.

Directory structure of the ROOT module that uses the subdirectories named examples, pages, and partials.

The directory name, ROOT, as well as when the module coordinate, ROOT, is used in a resource ID, must be written in uppercase.

We recommend you create a ROOT module directory in your component because Antora automatically applies component-level URLs to the page files stored in it. When the pages in the ROOT module are published, these pages are promoted a level above any other modules’ pages in that component’s URL. This means that, unlike the named modules, the directory name ROOT isn’t displayed in the site’s output path. You can see an example of a ROOT page’s URL in URLs for ROOT module pages.

Small documentation components may never need more than a ROOT module. However, as your project grows, you can easily add more modules and gradually redistribute the content without having to restructure the project. So while the extra structure seems like overkill now, in the long run, you’ll be glad you gave your content the space to grow.

Now, let’s review the requirements of each of the family subdirectories in more detail.

What is a family?

A family is a collection of files in a module that share the same content type or output role. These files are stored in the standardized family subdirectories, attachments, examples, images, pages, and partials, within a module. Antora automatically assigns preset behavior to the files it finds in these subdirectories. Example, image, page, and partial files can be referenced by any module or component using Antora’s resource IDs. (The ability to reference attachments using a resource ID is coming soon.)

Attachments

The attachments subdirectory of a module

An attachment is a resource, such as the ZIP archive of a sample project, that a site visitor can download via a link. Attachment files are saved in the attachments directory. A link to an attachment is created using the AsciiDoc link macro.

Binaries and other large files

If your documentation component contains 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).

Examples

The examples subdirectory of a module

The examples directory contains non-AsciiDoc file types, such as source code or sample data sets. An example is inserted into a page using the AsciiDoc include directive and the example’s resource ID.

Images

The images subdirectory of a module

Photographs, diagrams, screenshots, and other graphics files are saved in the images directory. They’re inserted into a page using the block or inline image macros. AsciiDoc supports PNG, JPG, SVG, and GIF (static and animated) image file formats.

Pages

The pages subdirectory of a module

AsciiDoc files destined to become site pages are stored in the pages directory of a module. These files are converted to HTML and automatically published as individual pages in the generated site.

URLs for ROOT module pages

When the AsciiDoc files stored in the pages directory of ROOT are published to a documentation site, they’re promoted a level above any other modules’ pages in that component’s URL. To demonstrate this concept, let’s compare the URLs of two pages, one from a ROOT module and one from a named module. The standardized directory structure illustrated in Figure 2 contains the documentation for a software product named Hyper Lemur. Notice that there is a file named deploy.adoc in the pages directory of ROOT.

hyperlemur dir structure
Figure 2. Directory structure of the Hyper Lemur documentation.

When Antora generates a site that includes the documentation for Hyper Lemur, the URL for the page created from the deploy.adoc file would look like this.

ROOT module page URL

The base URL, https://my-company.com, is set in the playbook Antora uses to generate the site. The component name segment, hyperlemur, is set by the name key in the component descriptor. The version segment, 1.0, is set by the version key in the component descriptor. The page name segment, deploy, is the basename of the AsciiDoc file deploy.adoc.

Notice that the name of the module, ROOT, isn’t in the URL. Now, let’s see what the URL of a page stored in the named module, admin, would look like.

URLs for named module pages

AsciiDoc files stored in the pages directory of named modules are preceded by the name of the module. The module name is the name of the module directory where that page is stored. Using the Hyper Lemur documentation shown in Figure 2, let’s see what the URL for the user-management.adoc file stored in the pages directory of the admin module would look like.

Named module page URL

Notice that the name of the module, admin, is in the URL directly after the documentation component’s version.

Partials

The partials subdirectory of a module

Partials are AsciiDoc files that contain reusable content snippets such as product descriptions and definitions. They’re stored in the partials directory in a module. A partial file or a tagged portion of a partial file is inserted into a page using the AsciiDoc include directive and the partial’s resource ID.

Assets

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

The assets subdirectory of a module that contains an images folder and an attachments folder

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