Latest Version Segment
latest_version_segment key replaces the actual version with the symbolic version in the published URLs of the latest component versions.
As the key’s name implies, it only applies to the latest version of each component version in a site.
latest_version_segment key is configured in the playbook under the
urls: (1) latest_version_segment: current (2)
|1||Type the parent key
The value assigned to the
latest_version_segment key is the symbolic version.
Antora replaces the actual version in the version segment of a URL with the symbolic version.
The symbolic version is only applied to the URLs of pages and assets that belong to the latest version of a component.
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_version_segment key cannot contain spaces, forward slashes (
/), or HTML special characters (
The value cannot be
null (which also means it cannot be missing or
The value can only be an empty string if the value of
The value cannot be an empty string if the value of
This restriction is due to the fact that adding a redirect on the parent folder could prevent access to other versions.
This section explores the results of assigning a symbolic version to the
The examples in this section use the component versions defined by the component version descriptor files shown in Example 2 and Example 3.
Example 2 defines a component version with the name
colorado and version
name: colorado version: '5.2' (1)
Example 3 defines a component version with the name
colorado and version
name: colorado version: '5.6' (1)
Both component versions have a page named tour.adoc that belongs to the module get-started.
First, let’s review the URLs Antora makes by default.
That is, when the
latest_version_segment key isn’t set in the playbook.
Example 4 specifies the site URL, assigned to the
url key, that Antora uses when building absolute URLs and when the URLs are displayed in a browser address bar.
site: title: The Ranges url: https://docs.example.com content: # ...
Assuming Example 2 and Example 3 are the only component versions in the site, Antora identifies colorado 5.6 as the latest version of the colorado component. Antora determines the latest component version and order of versions based on its semantic and named version sorting rules. Using information from the playbook and antora.yml files, Antora constructs the following URLs for the tour.adoc page in each component version.
As shown in Example 5, the version segment uses the actual version 5.2 for the tour.adoc page that belongs to the colorado 5.2 component version.
In Example 6, the version segment uses the actual version 5.6 for the tour.adoc page that belongs to the colorado 5.6 component version.
While there’s nothing in the URL to signify version 5.6 as the latest version of the component colorado, Antora applies the default sorting order in the reference UI, so version 5.6 is listed first under the colorado component name in the component version selector and first in the listed versions in the page version selector.
Now, let’s assign a symbolic version to replace the actual version in the page and asset URLs of the latest component versions.
latest_version_segment key is configured in the playbook file, not the component version descriptor files, because it applies to all of the latest component versions in a site.
Example 7 shows a truncated playbook file with the
latest_version_segment key defined.
site: title: The Ranges url: https://docs.example.com urls: latest_version_segment: stable (1) content: # ...
In Example 8, the version segment uses the actual version because colorado 5.2 isn’t the latest version of the colorado component.
However, in Example 9, the version segment uses the symbolic version, stable, because Antora determined colorado 5.6 is the latest version of the colorado component.
The actual version, 5.6, is still displayed in the reference UI menus. The symbolic version, stable, is only used in the URLs. To customize the value displayed in the reference UI menus, use the display_version key.
If you want to drop the version segment from the URL, you can do so by setting the value to empty string (which is different from no value, which represents
site: title: The Ranges url: https://docs.example.com urls: latest_version_segment: '' (1) content: # ...
|1||Set the value of the
A page in the latest version will now be accessible from a URL that does not include the version segment.
The version is no longer present in the URL.
The actual version, 5.6, is still displayed in the reference UI menus.
Recall that you cannot set the
latest_version_segment to empty string if the
The examples in this section assumed the
latest_version_segment_strategy key wasn’t set.
Therefore, when Antora detected the
latest_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