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.

Docs component sort order

First, Antora sorts component versions into components according to the title key defined in each component version’s antora.yml file. If the title key isn’t set, it falls back to the name key.

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 name, a list of versions, sorted according to the component version sorting rules, is presented.

Versioning schemes

Antora only considers the value of the version key when sorting the component versions of a component. The value you assign to the version key determines what versioning scheme, and therefore what order, that component version is placed in under its component name in the component version selector menu.

Scheme Valid Identifiers Example

Semantic

Integer
String that starts with a number and contains at least one dot (.) character
String that starts with v, followed by a number, and contains at least one dot (.) character

30
2.4
v90.3

Named

All values that don’t match the semantic scheme

edge
master
z4

Unversioned

master

master
The version master has special meaning when a component version is unversioned or version-less, but it’s given no special treatment when sorting.

Component version sorting rules

Antora applies the following rules when sorting component versions:

  1. Named versions of a component are displayed in the component version selector menu before semantic versions if both are present.

  2. Named versions of a component are sorted in reverse alphabetical order (e.g., z4, master).

    1. Version identifiers with uppercase letters aren’t recommended in URLs and can prevent portability between web servers. If you do use uppercase letters, they come before lowercase letters (e.g., A, a).

  3. Semantic versions of a component are displayed in the component version selector menu after named versions if both are present.

  4. Semantic versions of a component are sorted in descending order

    1. The leading v in a semantic identifier is ignored and versions are sorted according to the first number after the v.

    2. The semantic versioning ordering rules are applied.

Determine the version order of a component

Let’s assume that the component RoseyDB contains several component versions. Some versions use the semantic scheme: v2.5, 4.0, and 3.9. Some are named: utopia, master, and vivid. According to Antora’s sorting rules, the RoseyDB component versions will be displayed in the reference UI in the order listed below.

Sorted RoseyDB component versions
vivid
utopia
master
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 version key. 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 5.0, the RoseyDB versions will still be sorted in the same order. The utopia version is just labeled with a different version name in the reference UI.

vivid
5.0
master
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.

Latest component version

In addition to sorting the component versions, Antora identifies the most recent, stable component version of each component. 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.)

Antora uses the latest version of a component when qualifying an incoming page or 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 latest in the UI model.