Component Versions and Branches

Versions of a documentation component are stored in branches in a version control repository such as git. The name of the branch itself doesn’t matter. It’s the version property in the component descriptor that determines the name of the version for the component.

Branches as versions

Like with software, we use branches to store different versions of the documentation. Branches are ideally suited for managing multiple versions of the same content.

If we didn’t use branches to specify versions, but instead used folders with trailing version numbers, all stuffed in a single branch, then we’d have to explicitly duplicate all the files in a documentation component for each version. And we’d have no easy way to compare, manage, and merge different instances of a document.

Branches handle all this for us. Creating a new branch is extremely cheap. You simply create a new branch from an existing reference in the repository, and the repository only stores what’s changed since that branch point.

Setting the version for a branch

To set the version of documentation stored in a particular branch, you specify the version in the component descriptor:

name: versioned-component
version: '2.1'
title: Versioned Component

This component descriptor communicates that the files taken from this branch contribute to the 2.1 version of the component named versioned-component. The name of the branch could be v2.1 or v2.1-beta. It doesn’t matter.

The component descriptor is the only file you have to update when creating a new branch. All the page references for that component should be relative to the version, so you shouldn’t need to update any links. The next time you run Antora on the repository, you’ll see a new version in the component explorer drawer.

You may need to add the branch to your playbook file. Keep in mind that content sources are filtered by branch name, not by the version they contain. That’s because a single version can be spread out across multiple branches, or even multiple repositories.

How Antora sorts versions

Antora sorts the versions of each component. To attain the order you want, you need to understand Antora’s sorting rules.

Antora sorts component versions using the following rules:

  • Partition semantic versions and named versions.

    • A semantic version is identified either as an integer (e.g., 2 or 30) or a string that starts with a digit and contains at least one “.” character (e.g., 2.0.1 or 30.5). The semantic version may start with an optional leading “v” (e.g., v2.0.1), which is ignored when sorting.

    • All other versions are assumed to be named versions.

  • Sort named versions in reverse (i.e., descending) alphabetical order and add them to the list.

    • The assumption is that named versions that fall later in the alphabet are newer.

  • Sort semantic versions in descending order

    • Discard the leading “v”, if present.

    • Apply the ordering rules for semantic versioning as defined by https://semver.org.

Although the version master has special meaning when creating URLs for a component version, it’s treated as any other named version when sorting.

Here’s an example of a version list that has been sorted according to these rules:

wily
vivid
utopic
v3.10
v3.9
v2.0

Whenever Antora displays versions in the UI, it presents them in this order. Bear in mind that if a display version is specified, the display version is shown instead. To the reader’s eyes, the versions may not appear to be sorted as described. In effect, the display version allows the sortable version and the version displayed to be independent of one another.

Prerelease versions

A version may be designated a prerelease version by assigning a value to the prerelease property in antora.yml. For example:

name: versioned-component
version: '2.2'
prerelease: Beta
title: Versioned Component

This assignment has two effects:

  • The value of the prerelease property is combined with the value of the version property to generate the display_version (e.g., 2.2 Beta).

    • If the prerelease value begins with a hyphen (-) or dot (.), a space is not added between the values when combining them.

    • This computed value is replaced by the value of the display_version property, if set.

  • The prerelease version is skipped when determining the latest version, unless all versions are prerelease versions.

Choosing the latest version

In addition to sorting versions, Antora keeps track of the latest version of each component. The sorting rules previously covered impact how the latest version is selected.

The latest version is the first version in the sorted list that is not prerelease. If all versions are prereleases, then the first version in the list is used.

Antora uses the latest version when qualifying a resource ID if it cannot otherwise determine the version. It also uses the latest version when determining the default URL for a component.

The latest version is available as a property on each component in the UI model. The latest version information is typically used to inform the reader if there’s a newer version of the documentation available.

Versionless URLs

The version of the component is typically included as a segment in the URL of publishable files. The exception to this rule is if the version is the reserved word master. When the version is master, Antora removes the version segment from the URL (and output path) of all publishable files in that component version. If the version is any other value (e.g., latest), that value will be used in the URL (and output path) of the files.

Here’s an example of a component version that will have versionless URLs:

name: tutorials
version: master
title: Tutorials

A page in the versionless component shown in the previous example might have a URL such as /tutorials/build-a-restful-web-service.html. However, the version name is still referenced in resource IDs as normal (e.g., master@tutorials::build-a-restful-web-service.adoc).

If the component only has a single version, and that version is the reserved word master, we say that the component is a versionless component. Typically, the master version is only used for a versionless component.