Component Descriptor: antora.yml

When an antora.yml file is present in a repository or directory, Antora assumes that all of the subsequent files and subdirectories are part of a documentation component. Often referred to as the component descriptor, antora.yml has two crucial purposes:

Component marker: When Antora finds antora.yml in a repository or directory, it knows that it has located a documentation component. This ability to store a documentation component anywhere in a directory hierarchy allows you to maintain and manage a component (or part of a component) in a repository with the software it documents, a demo or sample project, or in its own repository.
Component information: antora.yml is referred to as the component descriptor because it describes the documentation component. It associates the files in the standard directory structure with the specified component name and version (explicitly referred to as the component version, if you want to get technical). This assignment of component information decouples the source files from the repository and branches in which they’re stored. It’s also used for constructing Antora’s resource IDs so you can reference pages, partials, examples, and images within a component and across components. Finally, the component descriptor identifies and orders the files Antora uses to build the documentation’s navigation.

Component descriptor requirements

The component descriptor file must:

be named antora.yml,
be written in valid YAML,
contain the required keys and their values, and
be located at the same directory level as the modules directory of a documentation component.

Example 1 shows the structure of a component descriptor file.

Example 1. antora.yml

name: name-of-component
title: The title of the component used for display in the UI
version: name-of-version
start_page: name-of-a-module:filename.adoc
nav:
- modules/name-of-a-module/nav.adoc
- modules/ROOT/nav.adoc

The name and version keys are always required. The title, display_version, start_page, and nav keys may be optional depending on the version name, structure, and file names associated with a documentation component.

`name`

The name key is the component coordinate that’s used when the component is referenced in a page cross reference, image macro, included example, or included partial.

name: leaf

The value can contain letters, numbers, underscores (_), hyphens (-), and periods (.). The value isn’t related to the name of the repository or directory the component it’s describing is stored in, though they may be the same or similar. For instance, a documentation component might be stored in a GitLab repository named Coco B’s Massive Quantum App but this doesn’t impact how Antora handles the component when it publishes a documentation site that uses it. Antora only uses the value assigned to the component’s name key when converting resource IDs and generating the URLs for the component’s pages.

To minimize the likelihood of portability issues between web servers, letters used in the component name and component version should be lowercase.

`title`

The title key is the display name for the component.

title: Silver Leaf

The UI uses it where ever the component is identified, including the:

This key is important because a component’s name may have characters that don’t work well in URLs or spaces that don’t work in Antora’s resource IDs. Also, if the name of your project ever changes, you can change the value of the title key, but not have to change any resource IDs or URLs. Let’s imagine the Coco B company decides to change their application’s name from Massive Quantum to Ultra Massive Quantum. All they have to do is change the value of the title key from Massive Quantum to Ultra Massive Quantum and the new application name will be displayed in their documentation site’s UI.

`version`

The version key is the version coordinate in the resource ID, version segment in the page URL, and, when display_version isn’t set, the version name displayed in the UI. It’s also used to sort multiple versions of the same component.

version: '5.6'

The value can contain letters, numbers, periods (.), underscores (_), and hyphens (-). If the value starts with a number, enclose it within a set of single quote marks (').

Version value examples

1
v2.0-beta
rawhide

If display_version isn’t set, version is also used in the:

Like with the name key, the version key isn’t related, though it may be similar, to the name of the repository branch where the component’s source files are stored. See Setting the version for a branch for more examples and Versionless components to learn how to create a versionless component.

`prerelease`

The prerelease key is a marker that this version is considered prerelease. Prerelease versions are skipped when selecting the latest version of a component (unless all versions are prereleases, in which case the normal rules apply).

prerelease: true

The prerelease key is not set by default.

`display_version`

To display a version in the UI that is different from the value specified in version, set the display_version key.

display_version: The Big One Dot 0

This key is useful when you want the version displayed in your site’s UI to contain a blank (empty) space. (The version key can’t contain spaces because it’s used as a resource ID coordinate.) The display version key is optional and strictly used for presentation in the UI. It does not affect resource IDs, the version segment in the page URL, or how versions are sorted.

Display version value examples

v2.0 Beta
Rawhide
'3.8 (EOL)'

If the value starts with a number, enclose it within a set of single quote marks (').

`start_page`

By default, Antora looks for a file named index.adoc in the ROOT module of a component. It uses this page as the component’s start page (e.g., https://example.org/component-name/2.5/index.html). If there isn’t an index.adoc file in the ROOT module, you must specify a file as the start page in the component descriptor.

start_page: getting-started:overview.adoc

The start_page key accepts a resource ID that points to an existing page in the component.

Start page value examples

security:get-started.adoc
ROOT:welcome.adoc
org-governance:help.adoc

If Antora can’t find index.adoc in a component’s ROOT module and a start page isn’t specified in the component descriptor, site visitors will be directed to a 404 page when navigating to that component from the component version selector on any page.

`nav`

The nav key accepts a list of navigation files.

nav:
- modules/ROOT/nav.adoc
- modules/module-three/nav.adoc
- modules/module-one/install-nav.adoc

Each value specifies the path to a navigation file (e.g., modules/name-of-module/name-of-nav-file.adoc). The order the values are listed in dictates the order the contents of the navigation files are assembled in the site’s component menu.