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

Antora sorts component versions into documentation components according to the title key defined in each component version’s antora.yml file. If the 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.

Versioning schemes

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 ~ and null define a component version as unversioned.

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 or the reserved version values (~, null)

edge
z4

Unversioned

~
null

~

Component version sorting rules

Antora applies the following rules when sorting the component versions of a component:

  1. An unversioned component version is displayed in the component version selector menu before named versions if both are present.

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

  3. Named versions of a component are sorted in reverse alphabetical order (e.g., z4, wish, lester).

    1. 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., A, a).

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

  5. 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 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
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 3.0, the RoseyDB versions will still be sorted in the same order. The 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.

Latest component version

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 latest in the UI model.