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. Understanding how Antora sorts versions is important when choosing your versioning scheme so you can achieve the ordering you want.
Antora applies the following rules when sorting component versions:
Separate named versions from semantic 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). A semantic version may begin with an optional leading “v” (e.g., v2.0.1), which is ignored when sorting.
All other versions are assumed to be named versions.
Although the version named
masterhas special meaning when creating URLs for a component version, it’s given no special treatment when sorting.
Sort named versions (including
master) 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.
Upper characters come before lower characters (e.g., "`A"` comes before "`a"`, meaning it’s newer)
Sort semantic versions in descending order and add them to the list.
Discard the leading “v”, if present.
Apply the ordering rules for semantic versioning as defined by https://semver.org.
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. The display version allows the sortable version to differ from the version displayed in the UI. Thus, to the reader’s eyes, the versions may not appear to be sorted in the order described.
A version may be designated as a prerelease version by assigning a value to the
prerelease property in antora.yml.
name: versioned-component version: '2.2' prerelease: Beta title: Versioned Component
This assignment has two consequences:
If the value of the
prereleaseproperty is a non-empty string, and the
display_versionis specified, the
prereleasevalue is appended to the value of the
versionproperty to generate the
prereleasevalue begins with a hyphen (
-) or dot (
.), no space is added when appending the
prereleasevalue is separated from the
versionvalue by a single space.
display_versionkey is set, that value overrides the computed value just described.
The version will be skipped when determining the latest version (unless all versions are prerelease versions, in which case it is not skipped).
In addition to sorting versions, Antora selects the latest version of each component. The sorting rules previously covered impact how the latest version is selected.
The latest version is normally the first version in the sorted list that’s not a prerelease. However, if all versions are prereleases, then the first version in the list is selected.
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 normally included as a segment in the URL of publishable files.
For example, if the version is a named version like
latest or a semantic version like
2.1, that value will appear in the URL (and, by association, the output path) of these files (e.g.,
The exception to this rule is if the version matches the reserved word
In this case, Antora does not include the version segment in the URL for publishable files in that component version.
Here’s an example of a component version that will have versionless URLs:
name: tutorials version: master title: Tutorials
A page with the filename
build-a-restful-web-service.adoc in this component version would have the URL
When making a qualified reference to this page, you’d still include the version as you normally would (e.g.,
If the component only has a single version, and that version matches the reserved word
master, we say that the component is a versionless component.
That’s because when the component only has one version, and that version doesn’t show up in the URL, it appears to the reader as though the component has no versions.
Most often, the
master version is only used when making a versionless component.