What is a module?

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.

Why modules?

You might be contemplating one or more of the following questions:

Why have modules?
Do we need all this structure?
Isn’t a component enough?

One thing we’ve learned about documentation is that it multiplies, often quickly and unpredictably. As more content is created and your documentation team grows, more often than not, you want to start grouping files into folders to make them easier to find and manage. Modules allow you to group text files and their associated assets together as your documentation expands, all while preserving the full capability of Antora’s page ID.

Modules are also perfect when one software project is incubating a potential subproject that may spin off as its own project in the future. It’s easy to later detach a module from a component and set it up as its own documentation component.

Module overview

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.

Directory structure of a component containing two modules. The ROOT module contains all of the optional module subdirectories and sample file type in each folder for context.

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

ROOT module

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

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

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:

  • AsciiDoc documents go in the pages folder.

  • Images go in the assets/images folder.

  • Code snippets go in the examples folder.

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 assets subdirectory of a module that contains an images folder and an attachments folder

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

  • assets/attachments

  • assets/images

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.

Attachment files

An attachment is a resource that you want your user to download, such as a PDF or a ZIP archive of a sample project. Attachment files are saved in assets/attachments. A link to an attachment is created in a page using the AsciiDoc link macro.

Image files

Image files are saved in assets/images. Supported image file formats include:

  • PNG

  • JPG

  • SVG

  • GIF (static and animated)

Images are inserted into a page using the AsciiDoc image macro (block or inline).

Large files and GitLab / GitHub

If your documentation component contains large asset files, we don’t recommend that you store them in a regular GitLab or GitHub repository. Instead, you should either host them in a binary repository such as Bintray or S3, or use git LFS (Large File Storage).

Example files

The examples subdirectory of a module

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.

The pages subdirectory of a module

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?

ROOT module page URL

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.

Module page URL

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

Learn more:

Partial AsciiDoc files

The partials subdirectory of a module

Partials are AsciiDoc files. They’re stored in the partials directory in a module. A partial is inserted into a standard page using the AsciiDoc include directive and the partial’s resource ID.