A version is defined by assigning a value to the
It’s important to understand how Antora uses the version and its related facets before committing to a versioning scheme.
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
The value of a
version key, in combination with the value of a
name key, defines a component version.
The version is fundamental to many of Antora’s operations. Antora uses the version:
identify the latest version of a component
apply routing rules
as the version segment in page and asset URLs, except when:
the assigned value is the tilde, ~, that defines an unversioned component version
display_versionkey is set and assigned a value in the component version’s antora.yml file
display_versionkey is set by Antora at runtime because the prerelease key is assigned an identifier
Content writers use the version as a coordinate in page and resource IDs when referencing a resource in another component version.
version key is set and assigned a value in a component version descriptor file (antora.yml).
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
name: star version: rigel (1)
|1||On a new line, type
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 (
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 (
5.1 are examples of semantic identifiers.
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 (
See Customize the Display Version to learn how to display an identifier that contains spaces, uppercase letters, and other characters in the UI menus.