Latest Version Segment

The 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

The latest_version_segment key is configured in the playbook under the urls key.

Example 1. antora-playbook.yml

urls: (1)
  latest_version_segment: current (2)

1	Type the parent key `urls`, followed by a colon (`:`), and press `Enter` to go to a new line.
2	The `latest_version_segment` key must be nested under the `urls` key. Type `latest_version_segment`, followed by a colon (`:`), and then type the symbolic version value.

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.

Value requirements

The same requirements that apply to the value of the version key also apply to the latest_version_segment key. 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 (&, <, or >). 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 latest_version_segment_strategy is redirect:to or replace. The value cannot be an empty string if the value of latest_version_segment_strategy is redirect:from. This restriction is due to the fact that adding a redirect on the parent folder could prevent access to other versions.

Specify a latest version segment

This section explores the results of assigning a symbolic version to the latest_version_segment key. 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 5.2.

Example 2. Component version descriptor (antora.yml file) defining the colorado 5.2 component version

name: colorado
version: '5.2' (1)

1	The `version` key in antora.yml defines the component’s actual version as `5.2`.

Example 3 defines a component version with the name colorado and version 5.6.

Example 3. Component version descriptor (antora.yml file) defining the colorado 5.6 component version

name: colorado
version: '5.6' (1)

1	The `version` key in antora.yml defines the component’s actual version as `5.6`.

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.

Example 4. Playbook (antora-playbook.yml file) showing site url value

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.

Example 5. URL for colorado 5.2 tour.adoc page

https://docs.example.com/colorado/5.2/get-started/tour.html

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.

Example 6. URL for colorado 5.6 tour.adoc page

https://docs.example.com/colorado/5.6/get-started/tour.html

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. The 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.

Example 7. Playbook (antora-playbook.yml file) defining a symbolic version

site:
  title: The Ranges
  url: https://docs.example.com
urls:
  latest_version_segment: stable (1)
content:
  # ...

1	The `latest_version_segment` is set under the `urls` key and assigned the value `stable`.

Using the component versions defined in Example 2 and Example 3 and the playbook in Example 7, Antora constructs the following URLs for the tour.adoc page in each component version.

In Example 8, the version segment uses the actual version because colorado 5.2 isn’t the latest version of the colorado component.

Example 8. URL for colorado 5.2 tour.adoc page when latest_version_segment is set

https://docs.example.com/colorado/5.2/get-started/tour.html

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.

Example 9. URL for colorado 5.6 tour.adoc page when latest_version_segment is set

https://docs.example.com/colorado/stable/get-started/tour.html

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 null).

Example 10. Playbook that defines an empty symbolic version

site:
  title: The Ranges
  url: https://docs.example.com
urls:
  latest_version_segment: '' (1)
content:
  # ...

1	Set the value of the `latest_version_segment` to empty string to drop the version segment from the URL.

A page in the latest version will now be accessible from a URL that does not include the version segment.

Example 11. URL for colorado 5.6 tour.adoc page when latest_version_segment is empty

https://docs.example.com/colorado/get-started/tour.html

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 latest_version_segment_strategy is redirect:from.

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:to and redirect:from strategies work with the latest_version_segment key.