Latest Prerelease Version Segment
latest_prerelease_version_segment key replaces the actual version in the URL of resources in the latest prerelease with a symbolic prerelease version.
In order for a version be classified as a prerelease, the component must also have at least one non-prerelease version.
If a component only has prerelease versions, the latest version is not classified as a prerelease even if the
latest_prerelease_version_segment key is configured in the playbook under the
urls: latest_prerelease_version_segment: unstable
The value assigned to the
latest_prerelease_version_segment key is the symbolic prerelease version.
Antora replaces the actual version in the version segment of the latest prerelease component versions’ URLs with the symbolic prerelease version.
A component version must be designated as a prerelease and Antora must determine that it is the latest prerelease of a component for the value assigned to the
latest_prerelease_version_segment key to be applied to its page and asset URLs.
Depending on the strategy assigned to the latest_version_segment_strategy key, Antora may apply additional redirect rules when routing to or from symbolic and actual version URLs.
The same requirements that apply to the value of the
version key also apply to the
The value can contain letters, numbers, periods (
.), underscores (
_), and hyphens (
To ensure portability between host platforms, use lowercase letters.
The value of the
latest_prerelease_version_segment key cannot contain spaces, forward slashes (
/), or HTML special characters (
The value can only be empty if the value of
The value cannot be empty if the value of
This restriction is due to the fact that redirecting from the parent folder could prevent access to other versions.
This section explores the results of assigning a symbolic prerelease version to the
The examples in this section use the component version defined by the component version descriptor file shown in Example 2.
Example 2 defines a component version with the name
colorado and version
name: colorado version: '6.0' (1) prerelease: -beta.2 (2)
The colorado 6.0 component version has a page named tour.adoc that belongs to the module get-started.
First, let’s review the URL Antora makes by default.
That is, when the
latest_prerelease_version_segment key isn’t set in the playbook.
By default, Antora uses the actual version in the version segment of page and asset URLs, even when the component version is a prerelease with an identifier.
Example 3 shows the default URL for the tour.adoc page that belongs to the
colorado 6.0 component version.
Now, let’s assign a symbolic prerelease version to the latest prerelease component versions in this site.
latest_prerelease_version_segment key is configured in the playbook file, not the component version descriptor files, because it applies to all of the latest prerelease component versions in a site.
Example 4 shows a truncated playbook file with the
latest_prerelease_version_segment key defined.
site: title: The Ranges url: https://docs.example.com urls: latest_prerelease_version_segment: next (1) content: # ...
Let’s assume that, according to its semantic and named version sorting rules, Antora determines that colorado 6.0 is the latest prerelease version of the colorado component. Using information from the playbook and the component version’s antora.yml file, Antora constructs the following URL for the tour.adoc page.
Now, in Example 5, the version segment contains the symbolic prerelease version, next.
The actual version with appended prerelease identifier, 6.0-beta.2, is still displayed in the reference UI menus. The symbolic prerelease version, next, is only used in the URLs. To customize the value displayed in the reference UI menus, use the display_version key.
The examples in this section assumed the
latest_version_segment_strategy key wasn’t set.
Therefore, when Antora detected the
latest_prerelease_version_segment key, it automatically set the
latest_version_segment_strategy key and assigned it the
replace strategy at runtime.
See Latest Version Segment Strategy to learn how the
redirect:from strategies work with the