Version Facets

The actual version is an identifier, that when combined with a component name, creates a unique identity for a collection of content and source files that are directly related to one another. This collection of source files is a component version. A component version always has an actual version. Even an unversioned component version has an actual version, defined as an empty string, for internal sorting and routing purposes.

A component version’s actual version is assigned to the version key in its component version descriptor (antora.yml). Alternatively, the actual version is extracted by Antora from a git refname based on the pattern assigned to the version key in antora.yml or on a content source in a playbook.

Content writers use the actual version to reference pages and assets in other component versions. Antora uses the actual version:

Each version facet—​prerelease, display, and symbolic—​described in the following sections, overrides a default behavior where Antora would otherwise use the actual version.

A version of a project or product that is made available before its final release is often called a prerelease version. Organizations use semantic versioning identifiers, such as -alpha.1, or special names, such as M1 or Snapshot, to communicate that a version is a prerelease to end users. To compliment a prerelease version of a project, a component version can be designated as a prerelease using the prerelease key.

A component version is designated as a prerelease when the prerelease key is assigned an identifier or the reserved value true in its antora.yml file. Using the prerelease key has the following benefits:

An actual version can’t contain spaces, uppercase letters, or certain characters that cause processing or portability errors. However, the actual version, when displayed in the UI menus, may not provide the appropriate experience if end users are expecting the version to be displayed with spaces, uppercase letters, or other symbols. In these circumstances, a display version should be assigned to a component version.

A display version is an identifier that is only used for presentation purposes in the UI menus. Unlike the actual version, the display version can contain spaces, uppercase letters, and other symbols or characters. The display version is specified using the display_version key in a component version’s antora.yml file. The display version is used by the UI where the version is displayed, including the component version selector and page version selector. The display version is never used in page or resource IDs, for component version routing and sorting, or in the version segment of URLs.

A symbolic version or symbolic prerelease version is a value that replaces the actual version in the version segment of a URL. The symbolic version or prerelease version are only applied to the URLs of the latest component version or latest prerelease, respectively. The symbolic version or prerelease version never applies to unversioned component versions. Because the symbolic version and symbolic prerelease version apply to all of the latest component versions or prerelease versions in a site, these values are assigned in your playbook, not in an individual component version’s antora.yml file. The symbolic version is assigned to the latest_version_segment key in the playbook. The symbolic prerelease version is assigned to the latest_prerelease_version_segment key in the playbook.