Component Descriptor: antora.yml
A documentation component must contain a component descriptor file named antora.yml.
This file serves two purposes:
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.
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.
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
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 - ...
|4||Start page key|
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 (
The component name does not have to be the same as the name of the repository it lives in.
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.
The component title does not have to be the same as the component name.
The value of the
version key is both the display name and version coordinate.
The value can contain letter, number, period (
.), underscore (
_), and hyphen (
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.
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.
start_page key accepts the page ID structure and must point to an existing page in the same component (e.g.,
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: 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