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.

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.

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.

modules/<user-defined-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:

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.

<module>/_attributes.adoc

Required; Reserved

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