How Component Versions are Sorted
On this page, you’ll learn:
How Antora sorts components and component versions.
How Antora selects the latest version of a component.
Understanding how Antora sorts component versions is important when choosing your versioning scheme and its potential presentation and routing results in your site’s UI.
Antora sorts component versions into documentation components according to the title key defined in each component version’s antora.yml file.
title key isn’t set, Antora falls back to the name key to sort the components.
Docs components are sorted in alphabetical order. The resulting alphabetical list of components is used for display purposes in the component version selector menu. Under each component title or name, a list of versions, sorted according to the component version sorting rules, is presented in the menu.
Antora only considers the value of the
version key when sorting the component versions of a docs component.
The value assigned to the version key determines what versioning scheme, and therefore what order, a component version is placed in under its component title or name in the component version selector menu.
The reserved values
null define a component version as unversioned.
All values that don’t match the semantic scheme or the reserved version values (
Antora applies the following rules when sorting the component versions of a component:
An unversioned component version is displayed in the component version selector menu before named versions if both are present.
Named versions of a component are displayed in the component version selector menu before semantic versions if both are present.
Named versions of a component are sorted in reverse alphabetical order (e.g.,
Version identifiers with uppercase letters aren’t recommended in URLs and can prevent portability between web servers. If you use uppercase letters, they come before lowercase letters (e.g.,
Semantic versions of a component are displayed in the component version selector menu after named versions if both are present.
Semantic versions of a component are sorted in descending order
vin a semantic identifier is ignored and versions are sorted according to the first number after the
The semantic versioning ordering rules are applied.
Let’s assume that the component RoseyDB contains several component versions.
Some versions use the semantic scheme:
Some are named:
According to Antora’s sorting rules, the RoseyDB component versions will be displayed in the reference UI in the order listed below.
vivid utopia 4.0 3.9 v2.5
Bear in mind that if the display_version key is defined in a component version’s antora.yml file, the value of
display_version is shown instead of the
version key’s value.
Regardless of whether or not
display_version is set, the component version is always sorted according to the value assigned to its
Thus, to the reader’s eyes, the versions may not appear to be sorted in the order described.
For instance, if the
utopia version of RoseyDB is assigned a
display_version value of
3.0, the RoseyDB versions will still be sorted in the same order.
utopia version is just labeled as
3.0 in the reference UI.
vivid 3.0 4.0 3.9 v2.5
Antora also determines the latest component version of each component.
The latest version for RoseyDB would be
vivid because it’s the first version in the sorted list and not defined as a prerelease.
In addition to sorting the component versions, Antora identifies the most recent, stable component version of each component.
The latest component version, also called the latest version, is the first version in the sorted list that’s not a prerelease.
If all versions are prereleases, then the first prerelease version in the list is selected.
An unversioned component version is always considered the latest version or latest prerelease version (if
prerelease is set).
Antora uses the latest version of a component when qualifying an incoming resource ID reference from another component if the version coordinate wasn’t specified or can’t otherwise be determined.
The latest version is available as the property