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)
          📄 a-source-file.adoc (6)
        📄 nav.adoc (7)

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 a page
7	A navigation file

At a minimum, a ROOT module directory 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. It’s recommended that you create a ROOT module directory because Antora applies special preset behavior to the pages in a ROOT module.

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.

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 target content that belongs to a ROOT module from another module or component version, you’ll specify the module name ROOT in the page IDs of cross references and the resource IDs for 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.