Organizing Your Documentation for Antora

Antora works with collections of documentation that follow a standard project structure. The benefits of this project structure are:

faster onboarding of contributors
interoperability with authoring, validation, migration, and bootstrap tools
the ability to define page and partial page references that:
- span components and component versions (and therefor repositories and their branches),
- aren’t coupled to output URLs, and
- can be automatically updated by a tool when source files are moved and renamed

We call a collection of documentation files organized under Antora’s standard project structure a documentation component.

Documentation component overview

A documentation component contains AsciiDoc text files and their assets, such as images, as well as a component descriptor file. Your site can be generated using just one documentation component or as many as you want.

When Antora receives instructions from your playbook to scan a repository, its first objective is to find a component descriptor file in that repository. The component descriptor file is named antora.yml. Once Antora finds this file, it assumes that that directory and all its files and subdirectories are a documentation component. The structure of a documentation component is laid out below.

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

The component illustrated in the above figure contains required and reserved directories and files as well as an example of an optional, user created module (name-of-module). When Antora encounters these folders and files in a properly structured component, it automatically assigns preset behavior and metadata to them.

Component preset legend

Required - Must be present in the documentation component.

Recommended - Should be present in the documentation component, but not required.

Optional - Doesn’t need to be created if the directory, file, or content type isn’t applicable to the component or module.

Reserved - Directory or file is associated with specific pipeline operations. The contents of a directory or file using a reserved name must adhere to certain requirements.

antora.yml: Required; Reserved

The component descriptor file tells Antora that the contents of the directory are a documentation component. This file contains crucial metadata about the documentation component.
modules: Required; Reserved

Except for antora.yml, all of the files in a component reside in this directory.
modules/ROOT: Recommended; Reserved

Directory that contains the ROOT module. This special directory does not appear in the output path. Instead, it becomes the parent folder of any additional, named modules that you create in a component. The directory name must be written in all uppercase letters.
modules/<name-of-module>: Optional

In addition to the ROOT module, you can create as many additional modules as your documentation component requires.

Each module, whether the ROOT module or an additional module, is structured as follows:

<module>/assets: Optional; Reserved

Directory where multimedia and supplemental files are organized by content type.
<module>/assets/attachments: Optional; Reserved

Directory that contains supplemental materials, such as PDFs or ZIP files, that readers can download via a link created in a page using the AsciiDoc link macro.
<module>/assets/images: Optional; Reserved

Directory that contains pictures, screenshots, diagrams, and other graphics files that are displayed in a page using the AsciiDoc image macro.
<module>/examples: Optional; Reserved

Directory that contains non-AsciiDoc file types, such as source code or data values. These files are often inserted into listing blocks using the AsciiDoc include directive.
<module>/pages: Required; Reserved

Directory that contains all of a module’s AsciiDoc files. These files are automatically enlisted by Antora and converted to standalone HTML pages.
<module>/partials: Optional; Reserved

Directory that contains AsciiDoc files that can be inserted into the files stored in pages. These files aren’t converted to HTML by Antora directly. Instead, they must be referenced by an include directive in a page in the pages directory.
<module>/nav.adoc: Optional; Reserved

A navigation file contains one or more AsciiDoc lists. Each navigation file must be declared in the component descriptor if you want it to be displayed in the component’s navigation menu.