版本键

通过为version键分配一个值来定义一个版本。在承诺采用版本控制方案之前，了解Antora如何使用版本及其相关方面非常重要。

什么是版本？

在Antora中，版本是从组件版本描述文件（antora.yml）中的version键解析出的值，或者从playbook中的内容源继承而来。版本是一个语义化或命名的标识符，代表项目文档的一个唯一发布或实例。version键的解析值，与name键的值结合，定义了一个组件版本。

尽管版本通常是一个字面值，但也可以被解释。版本可以通过将波浪符号~分配给version键来定义为无版本。版本也可以通过将true分配给version键来配置为所在的refname。版本还可以通过将refname投影映射分配给version键来从refname派生。

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

Antora如何使用版本

版本对于Antora的许多操作至关重要。Antora使用版本：

用于排序组件版本
识别组件的最新版本
应用路由规则
作为可发布资源URL中的版本段，除非：
- 分配的值是定义为无版本组件版本的波浪符号~
- 组件版本被标识为最新稳定版或最新预发布版，且在playbook中设置了latest_version_segment键或latest_prerelease_version_segment键
用于在参考UI的组件版本选择器和页面版本选择器菜单中进行显示，除非：
- 在组件版本的antora.yml文件中设置并分配了值的display_version键
- Antora在运行时设置了display_version键，因为预发布键分配了标识符

内容撰写者将版本用作在引用另一个组件版本中的资源时的版本坐标。

版本键

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

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

命名标识符作为版本

以下示例显示如何将命名标识符分配给version键。

示例1. 带有分配给版本的命名标识符的antora.yml

name: star
version: rigel (1)

1	在新行上，输入`version`，直接跟着一个冒号和一个空格（`:` ）。然后输入您想要分配给`version`的值。

语义标识符作为版本

语义标识符是一个整数或以整数开头并包含至少一个点（.）。10，1.0.0和5.1都是语义标识符的示例。尽管语义标识符看起来像一个数字，但实际上它是一个字符串。如果语义标识符与数字的语法匹配（整数或小数），如示例2中所示，您应该用一对单引号（'）将值括起来，这样可以将其强制转换为字符串。

以下示例显示如何将语义标识符分配给version键。

示例2. 带有分配给版本的语义标识符的antora.yml

name: colorado
version: '5.6.0' (1)

1	将与数字语法匹配的值用一对单引号括起来（`'`）。

Antora根据语义版本规则识别语义标识符。语义版本通常称为semver。Antora允许语义标识符以v开头。尽管此前缀保留在值中，但Antora在对版本进行排序时会忽略它。例如，v9.0.2将被排序，就好像该值是9.0.2一样。

refname作为版本

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

示例3. 带有true分配给版本的antora.yml

name: colorado
version: true (1)

1	值`true`告诉Antora使用refname作为值。

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

refname投影作为版本

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

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

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

示例4. 从refname投影计算版本的antora.yml

name: colorado
version:
  v(?<version>+({0..9}).+({0..9})).x: $<version> (1)
  feature/(*)/*: $1 (2)

1	匹配refname中的语义标识符，如`v2.0.x`，并提取它
2	提取以`feature/`开头的refname中第一个和第二个斜杠之间的值

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

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

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

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

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

值要求

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

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