What’s antora.yml?

antora.yml is a configuration file that serves two crucial functions.

  1. 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.

  2. 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

name

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

version

Version used with name to identify a component version. Used as the version coordinate in resource IDs and as the version segment for a component version’s published resource URLs, except when a component version is defined as unversioned.

Specifying the version key in a component version descriptor file is optional if the value of the key is inherited from the content source in the playbook. You can specify the version key on the content source if you want the value to be automatically derived from the refname or based on a refname mapping.

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

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 deactivates 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).