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 page and resource IDs, the version segment in the page URL, 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 empty 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 break Antora’s page and 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 page URLs, page IDs, and resource IDs.
The prerelease key provides additional UI routing, sorting, and presentation capabilities.
While the value of the
Assign a display_version to a component version
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 blank 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.