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.

title

The value of the title key is the display name for the component. It’s used anywhere in the UI that the component (or its super type, domain) is identified. This includes:

  • domain selector menu

  • domain selector drawer

  • first breadcrumb position

version

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

  • page ID and cross references (version@)

  • domain selector menu

  • domain selector drawer

  • page version selector

  • edit page URI (not visible)

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 (').

Example version key values
  • '1.0'

  • v2.0-beta

  • latest

start_page

By default, Antora automatically uses the file index.adoc in the ROOT module of a component as the start page of that component (i.e., https://company.com/docs/component/).

If a component doesn’t have an index.adoc file, then the start_page key must be set in the component descriptor file and assigned a page to use as the component’s start page. The value uses the page ID structure and must specify the module and page coordinates of the file.

Start page value examples
start_page: ROOT:overview.adoc

# or

start_page: security:protocols/ssh.adoc
A component must contain a file named index.adoc or a start page must be assigned to start_page in its 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 indicates the order the navigation menus will be displayed in the site’s navigation panel.