Modules, Families, and Subdirectories
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.
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.
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.
The ROOT module typically contains the content that’s directly associated with the documentation component itself.
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.
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.)
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.
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).
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.
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.
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.
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.
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.
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.
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.
Notice that the name of the module, admin, is in the URL directly after the documentation component’s version.
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.