Version键

版本是通过给版本键赋值来定义的。在提交版本控制方案之前，了解 Antora 如何使用版本及其相关方面是很重要的。

什么是版本

在 Antora 中，版本是从组件版本描述符文件(Antora .yml)中的版本键解析的值，或者是从剧本中的内容源继承的值。版本是一个语义或命名的标识符，表示项目文档的唯一版本或实例。版本键的解析值与名称键的值一起定义组件版本。

虽然版本通常是一个文字值，但它也可以被解释。通过给版本键赋一个波浪号 ~ ，可以将版本定义为未版本化的。通过将版本键赋值为 true ，可以将版本配置为它所在的 refname 。版本也可以通过将 refname 投影映射分配给 version 键来从 refname 派生。

有时，当需要在描述或示例中区分 version 和其它版本方面(如预发布、显示和符号)时，本文档中将分配给 version 键的值称为实际版本。

Antora如何使用version

这个版本是许多 Antora 操作的基础。Antora 使用该版本：

  • 对组件版本进行排序

  • 标识组件的最新版本

  • 应用路由规则

  • 作为可发布资源 url 中的版本段，除非：

    • 分配的值是一个波浪号( ~ )，它定义了未版本化的组件版本

    • 组件版本被标识为最新的稳定版本或最新的预发布版本，并且在剧本中设置了最新的版本段键(latest_version_segment key)或最新的预发布版本段键(latest_prerelease_version_segment key)

  • 用于在引用 UI 组件版本选择器和页面版本选择器菜单中显示，除非

    • 在组件版本的 antora.yml 文件中设置 display_version 键并分配一个值。

    • Antora 在运行时设置 display_version 键，因为 prerelease 键被分配了一个标识符。

当引用另一个组件版本中的资源时，内容编写者使用版本作为资源 id 中的版本坐标。

version键

version 键接受命名标识符（如 jesse ）、语义标识符（如 '1.5.0' ）、保留值 true 、refname投影的映射（例如 v/(?<version>*): $<version> ）或保留值 ~ 。 ~ 值将组件版本定义为未版本化。要了解如何指定未版本化的组件版本，请参阅创建一个没有版本的组件。

如果版本键是在组件版本描述符文件中为组件版本定义的，则它优先于剧本中内容源上定义的值。如果您希望剧本控制版本键的值，请不要在组件版本描述符文件中设置版本键。

命名标识符为版本

下面的示例显示如何将命名标识符分配给版本(version)键。

Example 1. Example 1. antora.yml with named identifier assigned to version
name: star
version: rigel (1)
yaml
1 在新行中输入 version ，后跟冒号和空格( : )。然后键入要分配给 version 的值。

作为版本的语义标识符

语义标识符要么是整数，要么以整数开头，并且至少包含一个点( . )。10、1.0.0 和 5.1 都是语义标识符的例子。尽管语义标识符看起来像一个数字，但它实际上是一个字符串。如果语义标识符匹配数字(整数或十进制)的语法，如示例2中所示，则应该将值括在一对单引号( ' )中，这将其强制转换为字符串。

下面的示例展示了如何为版本(version)键分配语义标识符。

Example 2. Example 2. antora.yml with semantic identifier assigned to version
name: colorado
version: '5.6.0' (1)
shell
1 将与数字语法匹配的值括在一对单引号( ' )中。

Antora 根据语义版本控制规则识别语义标识符。语义版本控制通常被称为 semver 。Antora 允许以 v 开头的语义标识符，尽管这个前缀保留在值中，但在对版本进行排序时，Antora 将忽略它。例如，v9.0.2 将按照值 9.0.2 进行排序。

重新命名为版本

由于 Antora 中的内容是从 git 存储库中检索的，因此您可能希望使用 git refname (分支或标签名称)，其中组件版本描述符被存储为版本。为此，将保留值 true 赋给版本，如示例3所示。

Example 3. Example 3. antora.yml with true assigned to version
name: colorado
version: true (1)
yaml
1 值 true 告诉 Antora 使用 refname 作为值。

Antora 会自动使用 refname 替换 true 键的值。Antora 使用的值始终是短 refname（例如 v1.0 ），而不是完整的 refname（例如 refs/heads/v1.0 ）。

将refname投影作为版本

重命名可能不够细，不能用作版本。此外，相同的 git 树可以通过具有不同命名方案的 git 引用传递，例如功能分支。在这些情况下，您希望从重新命名中提取或派生版本，而不是原样使用该值。这时您就可以使用 refname 投影来定义版本。

refname 投影表示为模式(键)和替换(值)的映射。refname 投影允许您使用模式匹配 refname ，然后基于该匹配构建一个版本。模式告诉 Antora 使用哪个入口以及从中提取哪些部分。替换告诉 Antora 如何从匹配的 refname 派生一个版本。

下面的示例展示了如何使用投影从 refname 中计算版本(version)键的值。

Example 4. Example 4. antora.yml with version computed from a refname projection
name: colorado
version:
  v(?<version>+({0..9}).+({0..9})).x: $<version> (1)
  feature/(*)/*: $1 (2)
yaml
1 匹配 refname (如 v2.0.x )中的语义标识符并提取它
2 提取以 feature/ 开头的 refname 的第一个和第二个斜杠之间的值

投影中的关键是一个 glob 模式( extglos 、 range 和一些正则表达式结构的组合)。该模式具有与用于匹配剧本中内容源的分支或标记的模式相同的匹配功能。

模式中的圆括号(即圆括号)之间的字符定义了一个匹配组。如果前大括号以 ?<name> 开头，则将该组赋值给尖括号之间指定的名称。否则，将根据组在模式中的位置为组分配一个以 1 为基础的索引。

匹配组可以在替换中引用。匹配组引用前面有一个美元符号( $ )。可以使用 $<name> 引用命名组，其中的名称再次在尖括号之间指定。索引组可以通过其编号引用，例如 $1 。您可以使用 $& 引用整个重命名。

如果匹配组包含任何正斜杠，则 Antora 将用连字符替换每个斜杠。

Antora 将使用它匹配的第一个模式的值。如果没有任何模式与 refname 匹配，那么 Antora 将退回到使用 refname 作为版本。

version键值要求

分配给版本(version)键的文字值可以包含字母、数字、点(.)、下划线(_)和连字符(-)。为了确保主机平台之间的可移植性，版本值中使用的字母应该是小写的。

该值不能包含空格、斜杠(/)或 HTML 特殊字符(&、< 或 >)。请参阅自定义显示版本，了解如何在 UI 菜单中表示包含空格、大写字母和其它字符的版本。