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:

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 blank spaces or forward slashes (/).

To minimize the likelihood of portability issues between web servers, letters used in the name key’s 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:

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 (-). It cannot contain blank spaces or forward slashes (/).

To minimize the likelihood of portability issues between web servers, 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.

  1. Open a new file in the text editor or IDE of your choice.

  2. On the first line, type name, directly followed by a colon (:).

  3. Insert a blank space after the colon, and then type the value you want to assign to name.

    name: silver-leaf
  4. At the end of the value, press Enter to go to the next line.

  5. Type version, directly followed by a colon (:), and then a blank space.

  6. 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'
  7. 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

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