What’s antora.yml?

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.

Why is antora.yml stored at a content source root?

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.

What information does antora.yml provide?

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:

Required Key Description

Required Key	Description
name	Component name used with `version` to identify a component version. Used as the component coordinate in page and resource IDs and in the component URL segment for a component version’s published pages.
version	Version identifier used with `name` to identify a component version. Used as the version coordinate in page and resource IDs and, with the exception of the reserved value `master`, in the version URL segment for a component version’s published pages.

name

Component name used with version to identify a component version. Used as the component coordinate in page and resource IDs and in the component URL segment for a component version’s published pages.

version

Version identifier used with name to identify a component version. Used as the version coordinate in page and resource IDs and, with the exception of the reserved value master, in the version URL segment for a component version’s published pages.

An antora.yml file can also contain any of the following optional keys:

Optional Key Description

Optional Key	Description
asciidoc.attributes	The `asciidoc` key accepts the `attributes` key and its nested list of key-value pairs. The key-value pairs listed under `attributes` represent built-in and user-defined AsciiDoc attributes (e.g., `idseparator: '-'`) and page attributes. Attributes in antora.yml are applied to all of the pages and resources (where applicable) that belong to a component version.
display_version	Version identifier used for presentation purposes only in the reference UI’s component version selector and page version selector. `display_version` accepts empty spaces, uppercase letters, and most characters (e.g., `3.0 Beta`, `RED WREN!`).
nav	Accepts a list of navigation files. Navigation files (e.g., nav.adoc) that are registered under the `nav` key are used in the component version’s page menu.
prerelease	Designates a component version as a prerelease version and disables the default routing rules. Key can append a prerelease identifier (e.g., `-alpha.2`) to `version` without affecting the version coordinate or version URL segment.
start_page	Specifies a page as the component version’s home page. By default, Antora uses index.adoc in a component version’s ROOT module.
title	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., `API Manager`).

asciidoc.attributes

The asciidoc key accepts the attributes key and its nested list of key-value pairs. The key-value pairs listed under attributes represent built-in and user-defined AsciiDoc attributes (e.g., idseparator: '-') and page attributes. Attributes in antora.yml are applied to all of the pages and resources (where applicable) that belong to a component version.

display_version

Version identifier used for presentation purposes only in the reference UI’s component version selector and page version selector. display_version accepts empty spaces, uppercase letters, and most characters (e.g., 3.0 Beta, RED WREN!).

nav

Accepts a list of navigation files. Navigation files (e.g., nav.adoc) that are registered under the nav key are used in the component version’s page menu.

prerelease

Designates a component version as a prerelease version and disables the default routing rules. Key can append a prerelease identifier (e.g., -alpha.2) to version without affecting the version coordinate or version URL segment.

start_page

Specifies a page as the component version’s home page. By default, Antora uses index.adoc in a component version’s ROOT module.

title

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., API Manager).