Component Version Descriptor

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against Antora 3.2.1 and checked on 2026-10-26. It describes antora.yml, the file that turns a directory of documentation files into a component version, and it uses the Pocket Units library (C# and Python) as the running example.

What the descriptor is

A component version is one version of one documentation component. Antora discovers it by looking for a file named antora.yml at the root of a content source (the repository root, or the folder selected with start_path in the playbook). The file must sit next to a modules directory; a content source root without a modules directory is ignored. The file is called the component version descriptor.

The descriptor does three jobs:

It identifies the component version: the name and version keys are the coordinates used in resource IDs and in published URLs.
It describes how the component version is presented: title, display_version and prerelease.
It configures the content: which navigation files to load (nav), which page is the home page (start_page) and which AsciiDoc attributes apply to every page (asciidoc.attributes).

Required keys

Only name and version are required.

Key Meaning

Key	Meaning
`name`	The component name. It is the component coordinate in resource IDs and the component segment of published URLs.
`version`	The version. It is the version coordinate in resource IDs and the version segment of published URLs.

name

The component name. It is the component coordinate in resource IDs and the component segment of published URLs.

version

The version. It is the version coordinate in resource IDs and the version segment of published URLs.

The name key

The value cannot be empty and cannot contain spaces, forward slashes or the HTML characters &, < and >. Letters, numbers, underscores, hyphens and periods are fine. Names are case sensitive, and lowercase is strongly recommended. The one exception is the reserved name ROOT: when it is combined with a versionless component (see below), the component is published at the site root and its name is omitted from URLs.

The version key

The value may be a named identifier (rigel), a semantic identifier ('5.6.0'), the reserved value true, a refname projection map, or ~ for a versionless component. The same character restrictions as for name apply, and lowercase is recommended. A leading v is kept but ignored when versions are sorted.

A value that YAML would read as a number, such as 2.0, must be quoted ('2.0'), otherwise it is not read as the string you intended.

If version is set in antora.yml, it takes precedence over a version defined on the content source in the playbook. Leave the key out of antora.yml when the playbook should decide the version. The values true and the refname projection map derive the version from the branch or tag name; they are covered in Versioning and Prerelease, and the content source options in Content Sources.

Presentation keys

The title key

title is optional. It is the human-readable label shown in the page menu, the component version selector and the first breadcrumb. If it is not set, the reference UI falls back to the component name. Unlike name, it may contain spaces, uppercase letters and most other characters. It never changes resource IDs or URLs. Antora uses the title of the latest version as the title of the component, so keep it the same in every version.

The display_version key

display_version is optional and affects presentation only. It is the label shown in the component version selector and the page version selector. If it is not set, the UI shows the value of version. It may contain spaces, uppercase letters and most other characters (for example 3.0 Beta). When the value starts with a number, wrap it in single quotes. It does not change resource IDs, URLs or sorting.

The prerelease key

prerelease marks the component version as a prerelease. It accepts the boolean true, or a non-empty identifier string such as -rc.3, Beta or SNAPSHOT. Setting it to false, or removing it, makes the version stable.

With an identifier that starts with a hyphen or a dot, the computed prerelease version is version plus the identifier, joined directly: version: '6.0.0' with prerelease: -rc.3 gives 6.0.0-rc.3.
With an identifier that starts with any other character, Antora inserts one space: version: '4.0' with prerelease: Beta gives 4.0 Beta.
If display_version is not set, the UI shows the computed value; if it is set, the UI shows display_version.
With an identifier, sorting uses the computed prerelease version. With true, sorting uses version.
Prereleases are skipped when Antora selects the latest version, unless every version of the component is a prerelease, and the default routing rules are not applied to a prerelease.

The identifier never changes the version coordinate in resource IDs or the version segment in URLs.

Content keys

The nav key

nav is a list of navigation file paths, each relative to antora.yml. Only registered files contribute to the page menu. With several files, the lists are combined into one menu in the order the paths are given: the first file is at the top and later files are appended. Navigation files themselves are described in Navigation.

The start_page key

start_page sets the home page of the component version. The value is the resource ID of a page in the same component version. It must begin at the module coordinate, and the module can be omitted for the ROOT module:

start_page: overview.adoc

Source: Antora docs: Choose a Start Page

start_page: guides:overview.adoc

Source: Antora docs: Choose a Start Page

Without the key, Antora uses index.adoc in the ROOT module. If there is no such page and no start_page, readers who click the component version reach a 404 page. This start page is separate from the site start page set in the playbook. In Antora 3.2.1 a start_page that points to a page that does not exist produces a warning at build time and the build continues with exit status 0:

{"level":"warn","name":"@antora/content-classifier","msg":"Start page specified for 2.0@pocket-units not found: guides:missing.adoc"}

The asciidoc attributes

Attributes under asciidoc.attributes apply to every page of the component version. Built-in attributes, custom attributes and page attributes (names starting with page-) can all be set:

asciidoc:
  attributes:
    product-name: Pocket Units
    page-status: draft@

Source: Antora docs: Assign Attributes to a Component Version

A plain value is hard set: pages cannot change it.
A trailing @ makes the value soft set: a page may override or unset it. Use '@' for an empty soft-set value.
~ hard unsets an attribute and false soft unsets it.
A value can refer to attributes declared earlier in the file or to site attributes. If a value begins with {, quote it.

Precedence runs from the playbook, through the component version, to the page. An attribute that is hard set or hard unset in the playbook cannot be changed by antora.yml, and a page can override only soft-set values of the component version. In Antora 3.2, attribute values need a YAML tag to be parsed as YAML and quotes are no longer stripped; see the Antora 3.2 release notes for the details. The playbook side is covered in Playbook.

Versionless components

A component version whose version is ~ (YAML null) is versionless:

name: shared-notes
title: Shared Notes
version: ~
nav:
- modules/ROOT/nav.adoc

Source: Antora docs: Define a Component with No Version

Antora then adds no version segment to the output path or URL, so a page is published at shared-notes/index.html rather than shared-notes/1.0/index.html. This holds even when the playbook sets latest_version_segment. Further rules:

A versionless component version sorts above the other versions of its component and counts as the latest version (or the latest prerelease when prerelease is set).
A reference from another component that names no version is routed to it. To address it explicitly, use the reserved version coordinate _, as in xref:_@shared-notes::index.adoc[].
For the menus, Antora assigns the display version default unless display_version is set, or a prerelease identifier supplies one.
A versionless component named ROOT is placed directly at the site root, and pages there can conflict with pages of named components.

Worked example with Pocket Units

The following descriptor was built with Antora 3.2.1 together with a small guides module:

name: pocket-units
title: Pocket Units
version: '2.0'
display_version: '2.0 Beta'
prerelease: true
start_page: guides:overview.adoc
nav:
- modules/ROOT/nav.adoc
- modules/guides/nav.adoc
asciidoc:
  attributes:
    product-name: Pocket Units
    page-status: draft@

Source: Antora docs: Component version descriptor

The site was built with a playbook listing this repository and a second repository holding the versionless shared-notes component above. The build printed no warnings and produced:

build/site/shared-notes/index.html
build/site/pocket-units/2.0/index.html
build/site/pocket-units/2.0/guides/overview.html

The version label in the page header read 2.0 Beta, the product-name attribute resolved to Pocket Units on both pages, the versionless page linked to the Pocket Units page with ../pocket-units/2.0/index.html, and the explicit xref:_@shared-notes::index.adoc[] resolved to index.html within its own component. Replacing display_version and prerelease: true with prerelease: Beta still showed 2.0 Beta, computed from the version and the identifier.

Pitfalls

An unquoted version: 2.0 is read by YAML as a number; quote it.
display_version and title do not change URLs or resource IDs; only name and version do.
prerelease does not alter the version segment of the URL, and it keeps the version out of the default routing.
The official documentation does not state what happens when an entry in nav points to a missing file; check the build log after registering a new navigation file.