Organizing Your Documentation for Antora

Antora works with collections of documentation that follow a standard, well-defined project structure. The benefits of a standard project structure for documentation are as follows:

  • faster onboarding of contributors

  • interoperability with authoring, validation, migration, and bootstrap tools

  • the ability to define page references that span component versions (and thus repositories), are not coupled to output URLs (source-to-source), and can be automatically updated by a tool when source files are moved and renamed

  • better organization system to manage files as the documentation grows

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

When you use documentation components, you can take advantage of the open source tools, plugins, and automated processes built to integrate with the Antora pipeline.

Documentation component overview

A documentation component is content that adheres to a standard, well-defined organization structure. This type of component contains of a collection of AsciiDoc text files and their assets, such as images, as well as a component descriptor file. All the documentation in a component should follow the same versioning scheme and be versioned together. 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 specific 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.

component dir structure

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 (user-named-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.


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.


Required; Reserved

Except for antora.yml, all of the files in a component reside in this directory.


Recommended; Reserved

Directory that contains the ROOT (aka top-level) module. This special directory does not appear in the output path. Instead, it becomes the parent folder of any user-defined modules. The directory name must be written in all uppercase letters.



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:


Optional; Reserved

Directory where multimedia and supplemental files are organized by content type.


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.


Optional; Reserved

Directory that contains pictures, screenshots, diagrams, and other graphics files that are displayed in a page using the AsciiDoc image macro.


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.


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.


Optional; Reserved

Directory that contains AsciiDoc files that can be inserted into the files stored directly under pages. These files are not converted to HTML by Antora directly. Instead, they must be referenced by an include directive in a page in the pages directory.


Required; Reserved

Helper file that enables assets, partials, and examples to be rendered in preview tools such as Atom and the Asciidoctor Chrome extension.


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.