Define a Component with No Version
Sometimes the project or process you’re documenting isn’t versioned. For example, hosted technology services and team handbooks may only need their content to represent how the service or process works as of right now. This is where the reserved version value of a tilde, ~, comes into play.
Assign ~ to the version key
To define a component version that doesn’t have a version, assign a tilde, ~, to the version key. The ~ is shorthand for the value null, which has the same effect.
name: component-name
version: ~ (1)| 1 | On a new line, type the key version, directly followed by a colon and a blank space (: ). Then enter the value ~. |
Antora doesn’t apply the same behavior and output rules to an unversioned component version that it does to a component version with a named or semantic version. For example, Antora doesn’t include the version segment in the publishable resource URLs of an unversioned component version (e.g., /component-name/module-name/page-name.html).
Behavior and output
The version key is required for a component version since versioning is central to how Antora works. The behavior and output rules that are influenced by the version are described in How Antora uses version. However, Antora accounts for the fact that some components aren’t versioned or have an unversioned version that’s co-located with actual versions. When the version key is assigned ~, defining the component version as unversioned, Antora:
-
sorts the unversioned component version above other versions that belong to the same component
-
identifies it as the latest version of a component or, if the
prereleasekey is set, as the latest prerelease version of a component -
assigns the fallback value
defaultto thedisplay_versionkey at runtime for display purposes in the UI menus, except when:-
the
display_versionkey is assigned a value in antora.yml, or -
the prerelease key is assigned an identifier and the
display_versionkey isn’t set in antora.yml; at runtime, Antora assigns the identifier to thedisplay_versionkey
-
-
doesn’t add a version segment to the unversioned component version’s publishable resource URLs, even if the latest_version_segment key or latest_prerelease_version_segment key is set in the playbook, unless the
latest_version_segment_strategyisredirect:from
|
UI and extension developers
When a component version is defined as unversioned:
|
Reference an unversioned resource
Because an unversioned component version is often the only version or always the latest component version in a component, Antora automatically routes any incoming references that originate from other components that don’t specify a version coordinate to it. However, in rare cases, such as when referencing an unversioned prerelease from another component version, you can use the reserved keyword _ (an underscore) as the version coordinate in the resource ID (e.g., xref:_@component:module:file.adoc[]) to reference an unversioned component version.