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.

Example 1. antora.yml for a versionless component version
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:

UI and extension developers

When a component version is defined as unversioned:

  • the reserved version value, ~ or null, is coerced into and stored as an empty string internally

  • a version segment isn’t added to pub.url or out.path

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-name.adoc[]) to reference an unversioned component version.