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 resolved from the version key in a component version descriptor, antora.yml, or inherited from the content source in the playbook. A version is a semantic or named identifier that represents a unique release or instance of the documentation for a project. The resolved value of the version key, in combination with the value of the name key, defines a component version.

Although the version is typically a literal value, it can also be interpreted. The version can be defined as unversioned by assigning a tilde, ~, to the version key. The version can be configured as the refname in which it resides by assigning true to the version key. The version can also be derived from the refname by assigning a map of refname projections to the version key.

Occasionally, the version is referred to as 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 the version coordinate in resource IDs when referencing a resource in another component version.

version key

The version key must be set and assigned a value in a component version descriptor, antora.yml. The version key accepts a named identifier, such as jesse, a semantic identifier, such as '1.5', the reserved value true, a map of refname projections, such as v/(?<version>*): $<version>, or the reserved value ~. The latter defines a component version as unversioned. To learn how to specify an unversioned component version, see Define a Component with No Version.

In all cases, if the version key is defined in the component version descriptor, it takes precedence over the value defined on the content source in the playbook. If you want the playbook to be able to control the value of the version key, don’t set the version key in the component version descriptor.

Named identifier as version

The following example shows how to assign a named identifier to the version key.

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 identifier as version

A semantic identifier is either an integer or begins with an integer and contains at least one dot (.). 10, 1.0.0, and 5.1 are all examples of semantic identifiers. Although a semantic identifier can look like a number, it’s actually a string. If the semantic identifier matches the syntax of a number (integer or decimal), like the one shown in Example 2, you should enclose the value in a pair of single quotes ('), which coerces it to a string.

The following example shows how to assign a semantic identifier to the version key.

Example 2. antora.yml with semantic identifier assigned to version
name: colorado
version: '5.6' (1)
1 Enclose a value that matches the syntax of a number in a pair of single quote marks (').

Antora recognizes semantic identifiers according to semantic versioning rules (aka semver). Antora also allows a semantic identifier to begin with v. Although this prefix is preserved in the value, Antora will ignore it when sorting versions. For example, v9.0 will be sorted as though the value is 9.0.

refname as version

Since content in Antora is retrieved from a git repository, you may want to use the git refname (branch or tag name) in which the component version descriptor is stored as the version. To do so, assign the reserved value true to the version. Antora will substitute the value true with the refname automatically. The value Antora uses is always the short refname (e.g., v1.0), not the full refname (e.g., refs/heads/v1.0).

The following example shows how to use the refname as the value of the version key.

Example 3. antora.yml with refname assigned to version
name: colorado
version: true (1)
1 The value true tells Antora to use the refname as the value.

refname projection as version

The refname may not be granular enough to use as the version. Furthermore, the same git tree could be passed through git references that have different naming schemes, such as feature branches. In these cases, you want the version to be extracted or derived from the refname rather than using the value as is. That’s when you’d define the version using a refname projection.

A refname projection is expressed as a map of patterns (the keys) and replacements (the values). The refname projection allows you to match the refname using a pattern, then build a version based on that match. The pattern tells Antora which entry to use and what parts to extract from it. The replacement tells Antora how to derive a version from the matched refname.

The following example shows how to use a projection to compute the value of the version key from the refname.

Example 4. antora.yml with version computed from a refname projection
name: colorado
version:
  v(?<version>+({0..9}).+({0..9})).x: $<version> (1)
  feature/(*)/*: $1 (2)
1 Matches the semantic identifier in a refname like v2.0.x and extracts it
2 Extracts the value between the first and second slash for a refname that begins with feature/

The key in the projection is a glob pattern (a combination of extglobs, ranges, and some regex constructs). The pattern has the same matching capabilities as the pattern used to match branches or tags for a content source in the playbook.

The characters between parentheses (i.e., round brackets) in the pattern defines a match group. If the opening brace begins with ?<name>, that group is assigned to the name specified between the angle brackets. Otherwise, the group is assigned to a 1-based index according to the group’s position in the pattern.

The match groups can be referenced in the replacement. A match group reference is preceded by a dollar sign ($). A named group can be referenced using $<name>, where the name is once again specified between the angle brackets. An indexed group can be referenced by its number, such as $1. You can reference the entire refname using $&.

If the match group contains any forward slashes, Antora will replace each one with a hyphen.

Antora will use the value of the first pattern it matches. If none of the patterns match the refname, Antora will fallback to using the refname as the version.

version requirements

The literal 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 represent a version that contains spaces, uppercase letters, and other characters in the UI menus.