Define a Component Name and Version

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

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 enter keys and values in an antora.yml file.

antora.yml requirements

A component version descriptor must:

be named antora.yml
be written in valid YAML
contain the name key and its value
contain the version key and its value
be stored at the same directory level as the modules directory

name key

A component name typically represents the name of your project, library, or service (e.g., fauna, rudder, nrepl). The name key is required and assigned in antora.yml.

Example 1. antora.yml with defined component name

name: colorado

The value can contain letters, numbers, underscores (_), hyphens (-), and periods (.). The value cannot contain a space, a forward slash (/), or HTML special characters (&, <, or >). The value cannot be empty.

To ensure portability between host platforms, letters used in the name value should be lowercase.

Antora uses the name key when interpreting page and resource IDs and generating the URLs for the component version’s pages. Unless the title key is set, it uses name for sorting components in the component version selector and where ever the component’s name is displayed in the reference UI, which includes the component version page menu, component version selector, and the first breadcrumb position on a component version’s pages.

version key

If you aren’t familiar with how Antora sorts component versions, see How component versions are sorted before committing to a versioning scheme.

A version, such as a named identifier (e.g., master, jesse, edge) or semantic identifier (e.g., 1.5, 8), is assigned to the version key in antora.yml.

The version key is required. Its value is used:

as the version coordinate in page and resource IDs
as the version segment in page URLs, unless assigned the reserved value master
to sort component versions in the reference UI
for display purposes, unless the optional display_version key is set, in the reference UI’s component version selector and page version selector

Example 2. antora.yml with defined component version

name: colorado
version: '5.6' (1)

1	Values that start with a number should be enclosed in a set of single quote marks (`'`).

The value can contain letters, numbers, periods (.), underscores (_), and hyphens (-). The value cannot contain a space, a forward slash (/), or HTML special characters (&, <, or >). The value cannot be empty.

To ensure portability between host platforms, letters used in the version value should be lowercase.

If a component version is a prerelease, you may want to set the optional prerelease key in addition to version. Unversioned or version-less component versions can be defined using the reserved value master.

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 the text editor or IDE of your choice.
On the first line, type name, directly followed by a colon (:).
Insert a blank space after the colon, and then type the value you want to assign to name.
```
name: silver-leaf
```
At the end of the value, press kbd:[Enter] to go to the next line.
Type version, directly followed by a colon (:), and then a blank space.
Type the value you want to assign to version. In this example, the value is enclosed in a set of single quote marks (') because it starts with a number.
```
name: silver-leaf
version: '7.1'
```
Save the file as antora.yml in the content source root. It should be located at the same hierarchy level as the modules directory to which you want it applied.

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 page and resource ID coordinates and in the URLs of the pages generated from the component version’s source files.

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 disables 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 disables 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).