Version Key

A version is defined by assigning a value to the version key. It’s important to understand how Antora uses the version and its related facets before committing to a versioning scheme.

What’s a version?

In Antora, a version is the value assigned to the version key in a component version descriptor file (antora.yml) or on a content source in the playbook. A version is a semantic or named identifier that often represents a unique or final release of the documentation associated with a project. A version can also be defined as unversioned by assigning a tilde, ~, to the version key. The value of a version key, in combination with the value of a name key, defines a component version.

Occasionally, the version is called the actual version when a distinction between version and the other version facets—​prerelease, display, and symbolic—needs to be made in a description or example.

How Antora uses version

The version is fundamental to many of Antora’s operations. Antora uses the version:

Content writers use the version as a coordinate in page and resource IDs when referencing a resource in another component version.

version key

The version key is set and assigned a value in a component version descriptor file (antora.yml). The version key accepts a named identifier, such as jesse, a semantic identifier, such as 1.5, or the reserved tilde (~), that defines a component version as unversioned. To learn about specify an unversioned component version, see Define a Component with No Version.

The following examples describe how to assign a named or semantic identifier to version.

Example 1. antora.yml with named identifier assigned to version
name: star
version: rigel (1)
1 On a new line, type version, directly followed by a colon and a space (: ). Then type the value you want assigned to version.

Semantic identifiers begin with a number. Antora allows the identifier to be prefixed with the letter v, which it ignores. Enclose values that start with a number, like the one shown in Example 2, in a set of single quote marks (').

Example 2. antora.yml with semantic identifier assigned to version
name: colorado
version: '5.6' (1)
1 Enclose values that start with a number in a set of single quote marks (').

Antora recognizes semantic identifiers according to the semantic versioning rules. A semantic identifier is an integer, begins with a number and contains at least one dot (.), or begins with v, followed by a number, and contains at least one dot (.). 3, v9.0, and 5.1 are examples of semantic identifiers.

version requirements

The value assigned to the version key can contain letters, numbers, periods (.), underscores (_), and hyphens (-). To ensure portability between host platforms, letters used in the version value should be lowercase.

The value cannot contain spaces, forward slashes (/), or HTML special characters (&, <, or >). See Customize the Display Version to learn how to display an identifier that contains spaces, uppercase letters, and other characters in the UI menus.