Modules

A documentation component is composed of one or more modules. A module is a discrete bundle of content, including text, images, and other source materials, organized in a hierarchy of folders by content type, then by optional topic (aka tag or category) if needed.

A documentation component can contain as many modules as you need or as few as one. If you only create one module in a component, we highly recommend that you name it ROOT because Antora automatically applies component-level URLs to the files in this module. The following figure illustrates a documentation component with a few example folders and files added for context. All of a component’s modules must be stored in modules.

Let’s examine the role the ROOT module and the requirements of the subdirectories a module can contain.

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

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. (You can see an example of a ROOT page’s URL in pages.) The directory name, ROOT, must be entered in all uppercase letters. When used in a page or resource reference, it must be entered in all uppercase letters.

Small documentation components may never need more than a ROOT module. However, if 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.

The ROOT module, as well as any other modules you create, should include the appropriate content type subdirectory when a module uses that content type.

For instance:

Each one of these folders can have an arbitrary depth of topic folders that are used to group files to make them easier for you to manage and navigate.

When a writer is working on the content, the module becomes the writer’s primary workspace. The writer doesn’t have to look elsewhere to find files that belong together. This arrangement mirrors how software developers work on source code.

Let’s look at each of these directories and their content type in more detail.

Any attachment or image files associated with a module must be stored in the corresponding content or media type subdirectory under that module’s assets directory.

The subdirectory names automatically recognized by Antora and associated to the corresponding AsciiDoc macros are:

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.

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

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

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.

Let’s say the component illustrated above is the documentation for your newest software product, Hyper Lemur. What would the URL for modules/ROOT/pages/deploy.adoc look like?

The base URL is set in the playbook. The component name, in this case hyperlemur, is set in the component descriptor. The page name segment is the basename of the AsciiDoc file. Notice that the name of the module, ROOT, isn’t in the URL. Files that are stored directly in the ROOT folder are published at the root of the component.

In contrast, pages that are stored in other modules will be preceded by the name of the module. Let’s see what the URL for modules/a-module/pages/user-management.adoc would look like.

The module name is the name of the module directory where that page is stored.

Learn more: