Module Directories and Modules

What’s the modules directory?

The modules directory is required wherever a component version descriptor file (antora.yml) is located.

📒 repository (1)
  📄 antora.yml (2)
  📁 modules (3)
  📁 non-docs-directory (4)

1	Content source root
2	Required component version descriptor file
3	Required modules directory
4	Antora won’t process the files in this directory because it’s located outside the modules directory

Except for antora.yml, the standard directories and their files must reside in a valid hierarchy in the modules directory. A modules directory can contain as many module directories as you require.

The modules directory keeps documentation source files isolated from configuration files, scripts, application code, tests, and other materials located in the content source root.

What’s a module directory?

Module directories must be stored in a modules directory. A module directory stores the source files for pages, reusable text and example snippets, images, and other content, in family directories. The source files stored in a module directory become part of a module in a component version.

📒 repository
  📂 docs (1)
    📄 antora.yml
    📂 modules
      📂 named-module (2)
        📂 pages (3)
          📄 page-source-file.adoc (4)
        📄 nav.adoc (5)

1	Content source root
2	A named module directory
3	pages family directory
4	A source file for a page
5	A navigation file

At a minimum, a module directory must contain at least one family directory with at least one source file. A module directory may also contain zero or more navigation files.

There are two types of module directories: named module directories and the ROOT module directory. At runtime, Antora collects the source files stored in the ROOT and named module directories and assigns them to modules. By convention, the module name corresponds to the name of the module folder.

What’s a module?

A module is a collection of content in a component version that’s related by concept, stage, feature, or other project-specific grouping. While the module does get represented as a URL segment in the published site, it’s primarily an organization tool for the writer. A module cannot be individually configured (meaning it has no metadata of its own).

The module name and the name of the module folder are the same. Antora assigns the module name to all files found inside the module’s folder.