ROOT Module Directory

What’s a ROOT module directory?

The ROOT directory is an optional module directory. A ROOT module directory is located in a modules directory, and its name must be written in all uppercase letters. A ROOT directory stores content source files in one or more of the family directories.

📒 repository
  📂 docs (1)
    📄 antora.yml (2)
    📂 modules (3)
      📂 ROOT (4)
        📂 pages (5)
          📄 index.adoc (6)
          📄 another-page.adoc (7)
        📄 nav.adoc (8)

1	Content source root
2	Required antora.yml file
3	Required modules directory
4	ROOT module directory
5	pages family directory
6	A source file for the default component version start page
7	A source file for another page in the ROOT module
8	A navigation file

If the ROOT module directory is present, it must contain at least one family directory with at least one source file. It can also contain an optional navigation file.

The source files stored in a ROOT directory become part of a ROOT module in a component version. We recommended that you create a ROOT module directory because Antora applies special preset behavior to the publishable resources in a ROOT module. For example, the source file index.adoc in the pages directory becomes the default start page for a component version. Those familiar with the terminology of HTML web hosting will recognize this as the index page for a component version.

Small documentation projects may never need more than a ROOT module directory. However, as your project grows, you can easily add more module directories and gradually reorganize your source files. While the extra structure seems like overkill now, in the long run, you’ll be glad you gave your content the space to grow.

Implicit ROOT module

If the content source root (i.e., the location of antora.yml) does not have a modules directory, then the content source root is assumed to be the ROOT module. In other words, you can put the pages directory and other family directories directly adjacent to the antora.yml file.

📒 repository
  📂 docs (1)
    📄 antora.yml
    📂 pages
      📄 index.adoc

This alternate layout is available per content source root (per origin in Antora lingo). In other words, the content source roots that make up a distributed component version may use different layouts for the ROOT module. It does not have to be uniform for each content source root for distributed component version.

If you later add the modules directory, then the files (e.g., pages) for the ROOT module must be moved to modules/ROOT.

What’s a ROOT module?

Source files that are stored in a ROOT directory become part of a module named ROOT in a component version. A ROOT module’s pages become the top-level pages of a component version. In other words, unlike other modules, the name of the ROOT module does not get used in the generated site.

You can think of the name “ROOT” as an alias for a blank module name (i.e., no module segment). Using this special value allows all modules to be siblings.

It’s important to carefully consider what files you store in a ROOT module directory since there is a potential for them to conflict with files in the named module directories. Generally, the ROOT module doesn’t use topic folders for this reason.

Where’s the ROOT module name used?

When you reference content that belongs to a ROOT module from another module or component version, you’ll specify the module name ROOT in the resource IDs for pages, attachments, images, examples, and partials. ROOT is always written in uppercase letters when it’s specified.

Since Antora considers the pages in a ROOT module to be top-level component version pages, the module name ROOT isn’t displayed in the module segment of its page URLs.