定义组件版本

在本页面上，您将学到：

antora.yml 文件必须满足的要求。
如何为 name 键分配有效值。
如何为 version 键分配有效值。
如何在 antora.yml 文件中定义其他键和值。

您了解什么是组件版本以及 antora.yml 的目的。

antora.yml 要求

组件版本描述符文件必须：

命名为 antora.yml
使用有效的 YAML 语法编写
包含带有有效值的 name 键
包含带有有效值的 version 键（除非在 playbook 中从内容源继承）
存储在与 modules 目录相同级别的位置

以下部分提供了有关创建 antora.yml 文件并为 name 和 version 键分配值以定义组件版本的说明。有关 name 和 version 的目的、Antora 如何使用它们、它们的具体要求以及更多用法示例的详细信息，请参阅 Name Key 和 Version Key。

为组件版本分配名称和版本

让我们创建一个定义组件版本名称和版本的 antora.yml 文件。在这个练习中，我们将为项目 Silver Leaf 创建一个组件版本。其组件名称将是 silver-leaf，版本将是 7.1。

在文本编辑器或 IDE 中打开一个新文件。
在第一行输入 name，紧接着一个冒号 (:)。
按下 Spacebar 在冒号后插入一个空格，然后输入要分配给 name 的值。 name 键不接受特定字符或值中的空格，请参阅名称要求了解详情。
```
name: silver-leaf
```
在值的末尾按 Enter 进入下一行。
输入 version，紧接着一个冒号 (:)，然后按下 Spacebar 插入一个空格。
输入要分配给 version 的值。在这个例子中，该值用单引号 (') 括起来，以免被解释为数字。
```
name: silver-leaf
version: '7.1'
```
version 键不接受特定字符或值中的空格，请参阅版本要求了解详情。
将文件保存为 antora.yml，保存在内容源根目录。 antora.yml 文件应该位于包含组件版本内容文件的 modules 目录旁边。

您现在已将一组源文件与一个组件版本关联起来！当 Antora 运行时，所有存储在标准一组目录中的源文件将被分配组件名称 silver-leaf 和版本 7.1。这些值将用作资源 ID 坐标并用于从组件版本源文件生成的可发布资源的 URL 中。

在定义组件的多个版本时，请确保始终使用相同的大小写。如果大小写不同（例如，Silver-Leaf 与 silver-leaf），Antora 将将其视为不同的组件。有关更多示例和值要求，请参阅 Name Key 和 Version Key。

可选的 antora.yml 键

您可以分配附加元数据，将组件版本指定为预发布版本，应用 AsciiDoc 属性，并使用组件版本描述符注册组件版本的导航列表和起始页面。

可选键描述

可选键	描述
asciidoc.attributes	`asciidoc` 键接受 `attributes` 键及其嵌套的键值对列表。在 `attributes` 下列出的键值对表示内置和用户定义的 AsciiDoc 属性（例如，`idseparator: '-'`）和页面属性。在 antora.yml 中的属性应用于属于组件版本的所有页面和资源（适用的情况下）。
display_version	仅用于演示目的的版本标识符，用于参考 UI 的组件版本选择器和页面版本选择器。 `display_version` 接受空格、大写字母和大多数字符（例如，`3.0 Beta`，`RED WREN!`）。
nav	接受导航文件列表。在 `nav` 键下注册的导航文件（例如，nav.adoc）将用于组件版本的页面菜单。
prerelease	将组件版本指定为预发布版本，并停用默认路由规则。键可以在不影响版本坐标或版本 URL 段的情况下向 `version` 添加预发布标识符（例如，`-alpha.2`）。
start_page	指定一个页面作为组件版本的主页。默认情况下，Antora 使用组件版本 ROOT 模块中的 index.adoc。
title	仅用于排序和演示目的的组件名称，用于参考 UI 的组件版本页面菜单、组件版本选择器和页面面包屑。接受空格、大写字母和广泛范围的字符（例如，`API Manager`）。

asciidoc.attributes

asciidoc 键接受 attributes 键及其嵌套的键值对列表。在 attributes 下列出的键值对表示内置和用户定义的 AsciiDoc 属性（例如，idseparator: '-'）和页面属性。在 antora.yml 中的属性应用于属于组件版本的所有页面和资源（适用的情况下）。

display_version

仅用于演示目的的版本标识符，用于参考 UI 的组件版本选择器和页面版本选择器。 display_version 接受空格、大写字母和大多数字符（例如，3.0 Beta，RED WREN!）。

nav

接受导航文件列表。在 nav 键下注册的导航文件（例如，nav.adoc）将用于组件版本的页面菜单。

prerelease

将组件版本指定为预发布版本，并停用默认路由规则。键可以在不影响版本坐标或版本 URL 段的情况下向 version 添加预发布标识符（例如，-alpha.2）。

start_page

指定一个页面作为组件版本的主页。默认情况下，Antora 使用组件版本 ROOT 模块中的 index.adoc。

title

仅用于排序和演示目的的组件名称，用于参考 UI 的组件版本页面菜单、组件版本选择器和页面面包屑。接受空格、大写字母和广泛范围的字符（例如，API Manager）。

要了解有关 version 键的功能以及将其与 Antora 提供的其他版本特性（预发布版本、显示版本和符号版本）进行比较的更多信息，请参阅版本特性。