Latest Version Segment Strategy

The latest_version_segment_strategy key controls the replacement and redirect direction between publishable URLs containing the actual version and URLs containing the symbolic version. As the key’s name implies, the selected strategy only applies to the latest version or latest prerelease version of a component version.

latest_version_segment_strategy key

The latest_version_segment_strategy key is optional. It’s configured under the urls key in the playbook. The latest_version_segment key or latest_prerelease_version_segment key must be set as well, otherwise Antora deactivates the specified strategy as there isn’t a symbolic version to replace the actual version with in the URLs. The specified strategy and symbolic version are only applied to the latest version or latest prerelease version of each component in your site. The URLs for all other component versions use the actual version in the version segment of the URL.

Example 1. antora-playbook.yml

urls: (1)
  latest_version_segment_strategy: redirect:to (2)
  latest_prerelease_version_segment: next (3)

1	Type the parent key `urls`, followed by a colon (`:`), and press `Enter` to go to a new line.
2	The `latest_version_segment_strategy` key must be nested under the `urls` key. Type `latest_version_segment_strategy`, followed by a colon and a space (`:` ), then type the built-in strategy value you want Antora to use, and press `Enter`. This example uses the value `redirect:to`.
3	Type `latest_prerelease_version_segment`, followed by a colon and a space (`:` ), and then type your symbolic version value. This example uses the symbolic version `next` for the latest prerelease version segment.

The latest_version_segment_strategy key accepts the following built-in values:

redirect:from: Sets up redirects from the URLs using the symbolic version to the URLs using the actual version, which may be empty. The actual version is replaced by the symbolic version specified by the latest_version_segment key or latest_prerelease_version_segment key in the latest component versions’ page and asset URLs. This strategy is currently ignored when the redirect facility is static.
redirect:to: Sets up redirects from the URLs using the non-emtpy actual version to the URLs using the symbolic version. The actual version is replaced by the symbolic version specified by the latest_version_segment key or latest_prerelease_version_segment key in the latest component versions’ page and asset URLs. No change is made to the URL if the version is empty. This strategy is transparently changed to replace when the redirect facility is static.
replace: Default. The non-empty actual version is replaced by the symbolic version specified by the latest_version_segment key or latest_prerelease_version_segment key in the latest component versions’ page and asset URLs. replace is the default value when the latest_version_segment_strategy key isn’t set, but the latest_version_segment key or latest_prerelease_version_segment key is assigned a value in the playbook. No change is made to the URL if the version is empty.

Antora creates temporary redirects (302) when the strategy is redirect:to or redirect:from. The format of the rules and redirect configuration file is determined by the redirect facility you specify using the redirect_facility key. Note that when the redirect_facility key isn’t defined in the playbook or CLI, Antora assigns the static value to the key at runtime. Since creating temporary redirect rules is only something a web server can do, when using the static redirect facility, the redirect:from strategy is ignored and the redirect:to strategy effectively becomes the replace strategy.

If the value of latest_version_segment_strategy key is redirect:from, the value of the latest_version_segment and latest_prerelease_version_segment cannot be empty. This restriction is due to the fact that redirecting from the parent folder could prevent access to other versions. For the same reason, the redirect:to and replace strategies have no affect if the actual version is empty.

Enable the replace strategy automatically

When replace is your preferred strategy, you don’t need to set the latest_version_segment_strategy key as long as you assign a value to the latest_version_segment key or latest_prerelease_version_segment key in the playbook.

Example 2. Use replace by default at runtime

  # ...
urls:
  latest_version_segment: stable
content:
  # ...

When Antora reads the playbook in Example 2 and detects that the latest_version_segment key is set and assigned a value but that the latest_version_segment_strategy key isn’t, Antora automatically sets latest_version_segment_strategy and assigns it replace at runtime. Likewise, if only the latest_prerelease_version_segment key is set and assigned a value, Antora automatically sets latest_version_segment_strategy and assigns it replace at runtime.

Redirect to the symbolic version URLs

This section explores the results of using the redirect:to strategy to redirect the URLs using the actual version of the latest component versions to the URLs using the symbolic version. The examples in this section use the component versions defined by the component version descriptor files shown in Example 3 and Example 4. Example 3 defines a component version with the component name colorado and the version 5.2.

Example 3. 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 4 defines a component version with the name colorado and the version 5.6.

Example 4. 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.

Now, let’s assign a latest version segment strategy and a latest version URL segment to the latest component versions. This information is provided to Antora using your site’s playbook file. The latest_version_segment_strategy and latest_version_segment keys are configured in the playbook file (not the component version descriptor file) under the urls key. Example 5 shows these keys defined in a playbook file.

Example 5. Playbook (antora-playbook.yml file) defining a latest version segment strategy

site:
  title: The Ranges
  url: https://docs.example.com
urls:
  latest_version_segment_strategy: redirect:to (1)
  latest_version_segment: current (2)
  redirect_facility: nginx (3)
content:
# ...

1	Antora will use the `redirect:to` strategy when generating the redirect rules for the latest component version URLs.
2	Antora will replace the actual version with the symbolic version, `current`, in the URLs of the latest component versions.
3	Antora will generate an nginx redirect file and place it at the root of the generated site at .etc/nginx/rewrite.conf.

Assuming Example 3 and Example 4 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.

As shown in Example 6, the version segment uses the actual version because colorado 5.2 isn’t the latest version of the colorado component.

Example 6. URL for colorado 5.2 tour.adoc page

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

However, in Example 7, the version segment uses the symbolic version, current, because colorado 5.6 is the latest version of the colorado component.

Example 7. URL for colorado 5.6 tour.adoc page

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

In addition to replacing the actual version with the symbolic version in the URLs of the latest component versions, Antora creates temporary redirects from the URLs using the actual version to the URLs using the symbolic version. The playbook in Example 5 assigns the nginx value to the redirect_facility key, therefore Antora writes the redirect rules to an nginx rewrite configuration file named rewrite.conf and places it in the site at .etc/nginx/rewrite.conf. Any request for a URL using the actual version of a latest component version, as long as the version is not empty, is redirected to the URL with the symbolic version. For example, if the URL https://docs.example.com/colorado/5.6/get-started/tour.html is requested, the URL redirects to https://docs.example.com/colorado/current/get-started/tour.html.

What happens when a new component version is added to the site?

Continuing the scenario presented in the previous section, let’s explore what happens when a new component version is added to the site. Example 8 defines a component version with the name colorado and the actual version 6.0.

Example 8. Component version descriptor (antora.yml file) defining the colorado 6.0 component version

name: colorado
version: '6.0'

The site uses the same playbook in Example 5. During generation, Antora determines that highest version of the colorado component is version 6.0, therefore colorado 6.0 becomes the latest version of the colorado component. Using the component versions defined in Example 3 (colorado 5.2), Example 4 (colorado 5.6), Example 8 (colorado 6.0), and the playbook in Example 5, Antora constructs the following URLs for the tour.adoc page in each component version.

Example 9 shows that the tour.adoc page URL in the component version colorado 5.2 remains the same.

Example 9. URL for colorado 5.2 tour.adoc page

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

Unlike the URL for colorado 5.6 in the previous section, Example 10 shows that the version segment for tour.adoc now contains the actual version because colorado 5.6 is no longer the latest version of the colorado component.

Example 10. URL for colorado 5.6 tour.adoc page

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

Nor does Antora set up temporary redirects from URLs with 5.6 to URLs with current. A request for https://docs.example.com/colorado/5.6/get-started/tour.html is served exactly as requested.

In Example 11, the version segment uses the symbolic version, current, because colorado 6.0 is the latest version of the colorado component.

Example 11. URL for colorado 6.0 tour.adoc page

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

Antora sets up new temporary redirects for URLs using the actual version of the latest component version, 6.0, and redirects them to URLs with the symbolic version. For example, if the URL https://docs.example.com/colorado/6.0/get-started/tour.html is requested, the URL redirects to https://docs.example.com/colorado/current/get-started/tour.html.