Customize the Display Version
display_version key is strictly used for presentation purposes in the reference UI when a version identifier contains uppercase letters, symbols, or blank spaces.
It doesn’t affect resource IDs, the version segment in the publishable resource URLs, or how component versions are sorted.
display_version key is optional.
It’s set in a component version’s antora.yml file and used by the reference UI where ever the version is displayed, including the component version selector and page version selector.
display_version isn’t set, the reference UI falls back to the version key.
version, the value of
display_version can contain spaces, uppercase letters, and most characters (e.g.,
name: colorado title: Colorado ∆ version: '5.6' display_version: '5.6 EOL' (1)
|1||If the value starts with a number, enclose it in a set of single quote marks (
display_version key should be used when a version contains spaces or characters that would break Antora’s resource IDs, prevent portability between web servers, and aren’t recommended in URLs.
It’s useful when the component version is a prerelease, unversioned, or archived because the value of
display_version doesn’t affect publishable resource URLs and resource IDs.
The prerelease key provides additional UI routing, sorting, and presentation capabilities.
While the value of the
To learn more about how Antora uses the
display_version key and compare it to the other version facets—actual version, prerelease version, and symbolic version—see Version Facets.
Let’s expand on the antora.yml example where you previously learned how to assign a component name and version.
The Silver Leaf project team wants the version code name in addition to its version number to be displayed in the UI.
version can’t contain blank spaces, let’s set
display_version in the component version’s antora.yml file.
Open the component version’s antora.yml file in the text editor or IDE of your choice.Example 2. antora.yml for the component version silver-leaf 7.1
name: silver-leaf title: Silver Leaf version: '7.1'
On a new line, type
display_version, directly followed by a colon (
Insert a blank space after the colon, and then type the value you want to assign to
display_version. Since the value begins with a number, enclose it in a set of single quote marks (
name: silver-leaf title: Silver Leaf version: '7.1' display_version: '7.1 Spiny'
Save the file.
Now, the UI will display 7.1 Spiny in the component version selector and page version selector.