Identify a Prerelease Version

The prerelease key informs Antora that a component version is a prerelease. When generating a site, Antora doesn’t apply the default routing rules to component versions designated as prereleases.

prerelease key

The prerelease key is optional. It’s set in a component version’s antora.yml file and assigned a user-defined identifier or the reserved true value. Antora doesn’t apply the default routing rules to a component version that is defined as a prerelease with the prerelease key, even if it’s the latest version in that docs component (unless all versions of that docs component are prereleases).

Assign an identifier to prerelease

A component version becomes a prerelease when the prerelease key is set in antora.yml and assigned an identifier. An identifier is a user-defined, non-empty string such as .alpha.2, YAY, Beta, and -rc.5. It can contain uppercase letters and a broad range of characters.

The component version defined in Example 1 is a prerelease.

Example 1. antora.yml with prerelease assigned the identifier -rc.3

name: colorado
title: Colorado ∆
version: '6.0'
prerelease: -rc.3 (1)

1	Assign an identifier to `prerelease` to designate the component version as a prerelease.

When prerelease is assigned an identifier, Antora computes an internal prerelease version value for UI sorting and, if display_version isn’t set, for display purposes. This computed prerelease version depends on the first character in the prerelease identifier.

Identifiers that begin with a hyphen(-) or dot(.)

The computed prerelease version takes the form of version-identifier or version.identifier. Antora directly appends the prerelease identifier to the version key’s value to compute the prerelease version. For instance, using Example 1, the computed prerelease version would be 6.0-rc.3.

Identifiers that begin with any other valid character

The computed prerelease version takes the form of version identifier. Antora separates the identifier from the version key’s value with one blank space to compute the prerelease version.

Example 2. antora.yml with prerelease assigned the identifier Beta

name: colorado
title: Colorado ∆
version: '6.0'
prerelease: Beta

Using Example 2, the computed prerelease version would be 6.0 Beta.

Unless the display_version key already has a value, Antora automatically assigns the computed prerelease version to it. If display_version is defined in antora.yml, then that value is displayed in the reference UI. However, the component version is still sorted according to the internally computed prerelease version value.

Assign true to prerelease

A component version becomes a prerelease when the prerelease key is set in antora.yml and assigned the value true.

Example 3. antora.yml with prerelease defined as true

name: colorado
title: Colorado ∆
version: '6.0'
prerelease: true

When prerelease is true, the component version is sorted by the value of version but the default routing rules aren’t applied to it even if it’s the latest version in that docs component. Also, there’s no visual cue displayed in the reference UI that indicates to a visitor that the component version is a prerelease version. To visually indicate in a site that a component version is a prerelease, you need to either:

define prerelease as true and assign a value to display_version that provides a prerelease version name or number, or
assign an identifier to prerelease.

Prerelease sorting and routing

Prerelease versions are skipped when Antora selects the latest version of a docs component (unless all component versions are prereleases, in which case the default rules apply). They’re sorted according to the versioning scheme criteria the computed prerelease version meets.