回退版本

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

version键

version键是可选的。version键接受一个命名标识符，比如jesse，一个语义标识符，比如'1.5'，保留值~（表示未版本化），保留值true，或者一个refname投影映射，比如v/(?<version>*): $<version>。

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

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

固定值作为版本

以下示例显示了如何将固定回退值分配给version键。固定值可以是命名标识符、语义标识符，或者值~表示未版本化。

示例1. 内容源将固定值分配给版本

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）中查找组件版本描述符时，它不会期望在该文件中找到定义的version键。相反，它将使用内容源上指定的version键的固定值（即2.0）。

refname作为版本

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

以下示例显示了如何将refname用作version键的回退值。

示例2. 内容源将refname用作版本

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

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

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

refname投影作为版本

refname可能不够精细，无法用作回退版本。此外，相同的git树可能通过具有不同命名方案的git引用传递。在这些情况下，您希望从refname中提取或派生版本，而不是直接使用该值。这时，您可以使用refname投影定义回退版本。

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

以下示例显示了如何使用投影计算version键的值。

示例3. 内容源从refname派生版本

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	匹配refname中的语义标识符，如`v2.0.x`，并提取它。
3	提取以`feature/`开头的refname中第一个和第二个斜杠之间的值

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

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

匹配组可以在替换中引用。匹配组引用以美元符号（$）开头。命名组可以使用$<name>引用，其中名称再次在尖括号之间指定。索引组可以通过其数字引用，例如$1。您可以使用$&引用整个refname。

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

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

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