Define a Component 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 file must:

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.

  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. 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
  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 press the Spacebar to insert a 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'

    The version key doesn’t accept certain characters or spaces in its value, see version requirements for details.

  7. Save the file as antora.yml in the content source root. The antora.yml file 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).