Define a Component Version

On this page, you’ll learn:

The requirements an antora.yml file must meet.
How to assign a valid value to the name key.
How to assign a valid value to the version key.
How to define additional keys and values in an antora.yml file.

You understand what a component version is and the purpose of antora.yml.

antora.yml requirements

A component version descriptor file must:

be named antora.yml
be written in valid YAML
contain the name key with a valid value
contain the version key (unless inherited from the content source in the playbook) with a valid value
be stored at the same directory level as the modules directory

The following section provides instructions for creating an antora.yml file and assigning values to the name and version keys to define a component version. For detailed information about the purpose of name and version, how Antora uses them, their specific requirements, and more usage examples, see Name Key and Version Key.

Assign a name and version to a component version

Let’s create an antora.yml file that defines the name and version of a component version. In this exercise, we’ll create a component version for the project Silver Leaf. Its component name will be silver-leaf, and its version will be 7.1.

Open a new file in your text editor or IDE.
On the first line, type name, directly followed by a colon (:).
Press the Spacebar to insert a space after the colon, and then type the value you want to assign to name. The name key doesn’t accept certain characters or spaces in its value, see name requirements for details.
```
name: silver-leaf
```
At the end of the value, press Enter to go to the next line.
Type version, directly followed by a colon (:), and then press the Spacebar to insert a space.
Type the value you want to assign to version. In this example, the value is enclosed in a set of single quote marks (') so it’s not interpreted as a number.
```
name: silver-leaf
version: '7.1'
```
The version key doesn’t accept certain characters or spaces in its value, see version requirements for details.
Save the file as antora.yml in the content source root. The antora.yml file should be located adjacent to the modules directory, which contains the content files for the component version.

You’ve now associated a set of source files with a component version! When Antora runs, all of the source files stored in the standard set of directories will be assigned the component name silver-leaf and the version 7.1. These values will be used as resource ID coordinates and in the URLs of the publishable resources generated from the component version’s source files.

Be sure to always use the same case when declaring the component name if you’re defining multiple versions of a component. If the case differs (e.g., Silver-Leaf versus silver-leaf), Antora will treat these as different components. See Name Key and Version Key for more examples and value requirements.

Optional antora.yml keys

You can assign additional metadata, designate a component version as a prerelease, apply AsciiDoc attributes, and register a component version’s navigation list and start page using the component version descriptor.

Optional Key Description

Optional Key	Description
asciidoc.attributes	The `asciidoc` key accepts the `attributes` key and its nested list of key-value pairs. The key-value pairs listed under `attributes` represent built-in and user-defined AsciiDoc attributes (e.g., `idseparator: '-'`) and page attributes. Attributes in antora.yml are applied to all of the pages and resources (where applicable) that belong to a component version.
display_version	Version identifier used for presentation purposes only in the reference UI’s component version selector and page version selector. `display_version` accepts empty spaces, uppercase letters, and most characters (e.g., `3.0 Beta`, `RED WREN!`).
nav	Accepts a list of navigation files. Navigation files (e.g., nav.adoc) that are registered under the `nav` key are used in the component version’s page menu.
prerelease	Designates a component version as a prerelease version and deactivates the default routing rules. Key can append a prerelease identifier (e.g., `-alpha.2`) to `version` without affecting the version coordinate or version URL segment.
start_page	Specifies a page as the component version’s home page. By default, Antora uses index.adoc in a component version’s ROOT module.
title	Component name used for sorting and presentation purposes only in the reference UI’s component version page menu, component version selector, and page breadcrumbs. Accepts empty spaces, uppercase letters, and a broad range of characters (e.g., `API Manager`).

asciidoc.attributes

The asciidoc key accepts the attributes key and its nested list of key-value pairs. The key-value pairs listed under attributes represent built-in and user-defined AsciiDoc attributes (e.g., idseparator: '-') and page attributes. Attributes in antora.yml are applied to all of the pages and resources (where applicable) that belong to a component version.

display_version

Version identifier used for presentation purposes only in the reference UI’s component version selector and page version selector. display_version accepts empty spaces, uppercase letters, and most characters (e.g., 3.0 Beta, RED WREN!).

nav

Accepts a list of navigation files. Navigation files (e.g., nav.adoc) that are registered under the nav key are used in the component version’s page menu.

prerelease

Designates a component version as a prerelease version and deactivates the default routing rules. Key can append a prerelease identifier (e.g., -alpha.2) to version without affecting the version coordinate or version URL segment.

start_page

Specifies a page as the component version’s home page. By default, Antora uses index.adoc in a component version’s ROOT module.

title

Component name used for sorting and presentation purposes only in the reference UI’s component version page menu, component version selector, and page breadcrumbs. Accepts empty spaces, uppercase letters, and a broad range of characters (e.g., API Manager).

To learn more about the capabilities of the version key and compare it to the other version facets Antora provides—prerelease version, display version, and symbolic version—see Version Facets.