定义一个不带版本的组件

有时，您正在记录的项目或流程没有版本控制。例如，托管的技术服务和团队手册可能只需要它们的内容表示该服务或流程现在的工作方式。这就是预留的版本控制关键字 ~ 发挥作用的时候。

将 ~ 赋给版本键

要定义一个没有版本的组件版本，请给版本键赋一个波浪号 ~ 。 ~ 是值 null 的简写，具有相同的效果。

Example 1. Example 1. antora.yml for a versionless component version
name: component-name
version: ~ (1)
1 在新行中，键入关键字版本(version)，后跟冒号和空格( : )。然后输入值 ~ 。

相比于命名或语义版本的组件版本 Antora 没有将相同的行为和输出规则应用于未版本化的组件版本。例如，Antora 不会在未版本化的组件版本的可发布资源 URL 中包含版本段（例如，/component-name/module-name/page-name.html ）。

行为和输出

组件版本需要版本(version)键，因为版本控制是 Antora 工作的核心。受版本影响的行为和输出规则在 Antora 如何使用版本中描述。然而，Antora 解释了这样一个事实，即某些组件没有版本化，或者具有与实际版本共存的未版本化版本。当分配版本(version)键为 ~ 时，将组件版本定义为未版本化，Antora：

  • 将未版本控制的组件版本排在属于同一组件的其他版本之上

  • 将其标识为组件的最新版本，或者(如果设置了预发布键)标识为组件的最新预发布版本

  • 为 UI 菜单中的显示目的，在运行时将回退值 default 分配给显示版本(display_version)键，除非：

    • 在 antora.yml 中为显示版本键分配了一个值，或

    • 在 antora.yml 中，预发布键被分配了一个标识符，而显示版本(display_version)键没有设置;在运行时，Antora 将标识符分配给显示版本键

  • 即使在剧本中设置了最新版本段键或最新预发布版本段键，也不会向未版本化的组件版本的可发布资源 url 添加版本段，除非最新版本段策略是 redirect:from

UI和扩展开发人员

当组件版本被定义为未版本化时：

  • 保留的版本值 ~ 或 null 在内部被强制存储为空字符串

  • 版本段未添加到 pub.url 或 out.path 。

引用未版本化的资源

由于未版本化的组件版本通常是组件中唯一的版本，或者总是最新的组件版本，因此 Antora 会自动将来自未指定版本坐标的其他组件的任何传入引用路由给它。但是，在极少数情况下，例如从另一个组件版本引用未版本的预发布版本时，您可以使用保留关键字 (下划线)作为资源ID中的版本坐标(例如，\xref:@component:module:file.adoc[] )来引用未版本的组件版本。