antora.yml is a configuration file that serves two crucial functions.
The presence of an antora.yml file at a content source root signals to Antora that it should find a sibling modules directory that contains source files that belong to a component version.
The antora.yml file at a content source root provides the required and optional component version metadata that Antora assigns to the source files it collects from the standard directories located in the modules folder.
Starting at each content source root, Antora looks for an antora.yml file. When it finds antora.yml, it searches for a sibling modules directory and considers all of its subdirectories and files to be part of a component version.
If Antora doesn’t find antora.yml at a content source root, it doesn’t look for a modules directory or collect any files from that location. This minimizes the chances of Antora wasting memory and CPU time to process source files that aren’t part of a documentation site.
The antora.yml files provide the ability to store your content source files anywhere in a directory hierarchy. As long as the content source root contains an antora.yml file, you can maintain and manage your content source files in a repository that also stores application code, tests, and other materials.
An antora.yml file is referred to as a component version descriptor because it provides required and optional information that identifies, describes, and configures a component version. In turn, this metadata and configuration is applied to all of the source files that belong to the component version.
This is why Antora can collect files from multiple repositories, directories, branches, and tags, and compile them into a single component version. Instead of processing files based on their file system or repository location, Antora converts files based on the information assigned to the source files by a component version descriptor file.
An antora.yml file contains the following required keys:
Component name used with
Version used with
An antora.yml file can also contain any of the following optional keys:
Version identifier used for presentation purposes only in the reference UI’s component version selector and page version selector.
Accepts a list of navigation files.
Navigation files (e.g., nav.adoc) that are registered under the
Designates a component version as a prerelease version and deactivates the default routing rules.
Key can append a prerelease identifier (e.g.,
Specifies a page as the component version’s home page. By default, Antora uses index.adoc in a component version’s ROOT module.
Component name used for sorting and presentation purposes only in the reference UI’s component version page menu, component version selector, and page breadcrumbs.
Accepts empty spaces, uppercase letters, and a broad range of characters (e.g.,