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.
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.
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.
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 semver.org.
Although the version
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.
A version may be designated a prerelease version by assigning a value to the
prerelease key in antora.yml.
name: versioned-component version: '2.2' prerelease: Beta title: Versioned Component
This assignment has two effects:
The value of the
prereleasekey is combined with the value of the
versionkey to generate the
prereleasevalue 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_versionkey, if set.
The prerelease version is skipped when determining the latest version, unless all versions are prerelease versions.
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.
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
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
However, the version name is still referenced in resource IDs as normal (e.g.,
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.
master version is only used for a versionless component.