定义一个组件版本

在此页面上，您将学习：

  • Antora.yml 文件是必需的。

  • 如何将有效值分配给名称(name)键。

  • 如何为版本(version)键分配有效值。

  • 如何在 antora.yml 文件中定义其它键和值。

    ASSUMPTIONS

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

antora.yml 必需

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

  • 被命名为 antora.yml

  • 是有效的 YAML 文件

  • 包含 name=value

  • 包含 version=value(除非从剧本中的内容源继承)

  • 存储在与 modules 目录相同的目录级别

以下部分提供了创建 antora.yml 文件的说明，并为名称和版本键赋值以定义组件版本。有关名称和版本的用途、Antora如何使用它们、它们的具体要求以及更多使用示例的详细信息，请参见名称键和版本键。

分配一个名称和版本给一个组件版本

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

  1. 在文本编辑器或 IDE 中打开一个新文件。

  2. 在第一行输入 name ，后面直接跟一个冒号( : )。

  3. 按空格键在冒号后插入空格，然后键入要分配给 name 的值。name 键在其值中不接受某些字符或空格，详细信息请参见名称要求。

    name: silver-leaf

  4. 在值结束时，按 Enter 键进入下一行。

  5. 输入 version 后跟 : ，然后插入一个空格。

  6. 键入要分配给 version 的值。在本例中，该值被括在一组单引号( ' )中，因此不会将其解释为数字。

    name: silver-leaf
version: '7.1'

    版本(version)键在其值中不接受某些字符或空格，详细信息请参见版本要求。

  7. 在内容源根目录中将文件保存为 antora.yml 。antora.yml 文件应该位于 modules 目录的旁边，该目录包含组件版本的内容文件。

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

TIP

如果你定义了一个组件的多个版本，在声明组件名时一定要使用相同的大小写。如果情况不同(例如， Silver-Leaf 和 Silver-leaf )， Antora 将把它们视为不同的组件。有关更多示例和值要求，请参见名称键和版本键。

可选 antora.yml 键

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

可选键 描述

asciidoc.attributes

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

display_version

版本标识符仅在引用 UI 的组件版本选择器和页面版本选择器中用于表示目的。显示版本接受空格，大写字母和大多数字符(例如，3.0 Beta , RED WREN!)。

nav

接受导航文件列表。在 nav 键下注册的导航文件(例如 nav.adoc )在组件版本的页面菜单中使用。

prerelease

指定组件版本为预发布版本，并禁用默认路由规则。可以附加一个预发布标识符(例如 -alpha.2 )到 version 键，而不会影响版本坐标或版本 URL 段。

start_page

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

title

仅在参考 UI 的组件版本页菜单、组件版本选择器和页面面包屑中用于排序和表示目的的组件名称。接受空格、大写字母和各种字符(例如 API Manager )。

要了解版本(version)键的更多功能，并将其与Antora提供的其他版本面进行比较，请参阅版本面。