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 versionless 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 versionless 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 are versionless or have an empty component version co-located with non-empty component versions.
When the version key is assigned ~, defining the component version as versionless, Antora:
-
sorts the versionless 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 versionless 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 versionless:
|
Reference a versionless resource
Because a versionless component version is typically the only version (or, at least, 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 a versionless 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 a versionless component version.