回退版本

version 键提供了一种从 playbook 直接控制与内容源对应的组件版本的方式。内容源上的 version 键是回退值。如果组件版本描述符（一个 antora.yml 文件）为组件版本定义了 version 键，则该键的值优先于内容源的 version 值。

version键

版本键是可选的。版本键接受命名标识符（例如 jesse）、语义标识符（例如 '1.5'）、保留值 ~（用于无版本）、保留值 true 或 refname 投影的映射，例如 v/(?<version>*): $<version>。

一个内容源可以匹配多个 git 引用。因此，只有当内容源配置为匹配单个引用，或者它匹配的所有引用都将文件贡献给同一组件版本时，才应使用固定值。否则，该键的值应该为 true 或 refname 投影的映射。

如果您希望 playbook 能够控制版本键的值，请不要在组件版本描述符（antora.yml 文件）中设置版本键。

固定值作为版本

以下示例演示如何为版本键分配固定的后备值。固定值可以是命名标识符、语义标识符或表示无版本的值。

Example 1. Content source with a fixed value assigned to version

content:
  sources:
  - url: https://git-service.com/org/repo-a.git
    branches: v2.0.x (1)
    version: '2.0' (2)

1	使用固定值时仅匹配单个引用。
2	分配一个固定值，例如命名标识符、语义标识符或值 `~`。

当 Antora 在指定分支（即 v2.0）中查找组件版本描述符时，它不会期望找到该文件中定义的版本键。相反，它将使用内容源上指定的版本键的固定值（即 2.0）。

refname 作为版本

由于 Antora 中的内容是从 git 存储库检索的，因此您可能需要使用内容源（存储组件版本描述符的位置）的 git refname（分支或标签名称）作为版本。为此，请将保留值 true 分配给版本键。Antora 会自动用引用名称替换值 true。

以下示例演示如何使用 refname 作为版本键的后备值。

Example 2. Content source that uses the refname as the version

content:
  sources:
  - url: https://git-service.com/org/repo-b.git
    branches: v* (1)
    version: true (2)

1	匹配任意数量的引用。
2	true 值告诉 Antora 使用匹配的引用名称作为值。

当 Antora 在指定分支（即 v2.0）中查找组件版本描述符时，它不会期望找到该文件中定义的版本键。相反，它将使用引用名称。Antora 使用的值始终是短引用名称（例如 v1.0），而不是完整的引用名称（例如 refs/heads/v1.0）。

refname 投影作为版本

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

引用名称投影表示为模式（键）和替换（值）的映射。引用名称投影允许您使用模式匹配引用名称，然后基于该匹配构建版本。该模式告诉 Antora 使用哪个条目以及从中提取哪些部分。替换告诉 Antora 如何从匹配的引用名称派生版本。

以下示例演示如何使用投影根据引用名称计算版本键的值。

content:
  sources:
  - url: https://git-service.com/org/repo-c.git
    branches: [v*, feature/*] (1)
    version:
      v(?<version>+({0..9}).+({0..9})).x: $<version> (2)
      feature/(*)/*: $1 (3)

1	将任意数量的引用与不同的命名模式相匹配。
2	匹配引用名称（如 v2.0.x）中的语义标识符并提取它。
3	提取以 feature/ 开头的引用名称的第一个和第二个斜杠之间的值

投影中的键是 glob 模式（extglob、范围和一些正则表达式构造的组合）。该模式与用于匹配 playbook 中内容源的分支或标签的模式具有相同的匹配功能。

模式中括号（即圆括号）之间的字符定义匹配组。如果左大括号以 ?<name> 开头，则该组将分配给尖括号之间指定的名称。否则，根据组在模式中的位置，为该组分配一个从 1 开始的索引。

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

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

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

Antora 支持使用通配符、排除、大括号、交替、范围和重复模式来匹配引用名称。请参阅内容源中的引用名称匹配。