Component Descriptor: antora.yml

A documentation component must contain a component descriptor file named antora.yml.

This file serves two purposes:

  1. Component marker: When Antora finds antora.yml in a repository, it knows that it has located a documentation component. This ability to “start” a documentation component anywhere in a directory hierarchy allows you to store a component in a repository with the software it documents, with a demo project, by itself, etc.

  2. Component information: antora.yml is a component descriptor file. It associates the files under this hierarchy with the specified component name and version (aka component-version), decoupling the files from the repository and branch in which they live. This information is used for creating links to pages in this component. The file also identifies files to use for site navigation.

Component descriptor requirements

A documentation component must have a component descriptor file. This file provides stable metadata that Antora and other tools can use when they need to retrieve information about the component and version.

The component descriptor must:

  • be located at the root of the documentation component (adjacent to the modules directory for that component)

  • be named antora.yml

  • be written in YAML

  • contain the required keys and values

Component descriptor structure
name: component-a (1)
title: Component A (2)
version: '1.0' (3)
start_page: module:filename.adoc (4)
nav: (5)
- modules/ROOT/nav.adoc
- modules/module-three/nav.adoc
- ...
1 Name key
2 Title key
3 Version key
4 Start page key
5 Nav key

name

The value of the name key is the component name that is used when the component is referenced in a cross reference. The value can contain letter, number, underscore (_), hyphen (-), and period (.) characters. The component name does not have to be the same as the name of the repository it lives in.

title

The value of the title key is the display name for the component. It’s used anywhere in the UI that the component is identified. This includes:

The component title does not have to be the same as the component name.

version

The value of the version key is both the display name and version coordinate. This includes:

The value is also used to sort multiple versions of the same component.

The value can contain letter, number, period (.), underscore (_), and hyphen (-) characters. If the value starts with a number, it must be contained within a set of single quote marks (').

The version key value isn’t related to a repository branch name or tag in any way. Instead, the value should be useable by the documentation writers and useful to the readers.

Example version key values

  • '1.0'

  • v2.0-beta

  • latest

If you want to use a different value when displaying the version in the UI, you can set the display_version key.

display_version: TheBigOneDot0

The value of the display_version key is strictly used for presentation. It does not affect how versions are sorted.

start_page

By default, Antora looks for a file named index.adoc in the ROOT module of each component to use as the start page for that component and version (e.g., https://example.org/component-name/index.html).

If the ROOT module doesn’t have an index.adoc page, you must specify a start page explicitly in the component descriptor. The start_page key accepts the page ID structure and must point to an existing page in the same component (e.g., ROOT:home.adoc, module-one:overview.adoc).

If a start page isn’t specified, and the component does not have a ROOT module with an index.adoc page, the reader will be directed to a 404 page when navigating to that component from the component version selector on any page.

Start page value examples
start_page: ROOT:home.adoc

# or

start_page: security:protocols/ssh.adoc
A component must have a ROOT module that contains an index.adoc page. Otherwise, a start page must be specified using the start_page key in the component descriptor.

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