什么是 antora.yml？

antora.yml 是一个配置文件，具有两个关键功能。

  1. 在内容源根目录中存在一个 antora.yml 文件，表示 Antora 应查找一个包含属于组件版本的源文件的同级 modules 目录。

  2. 内容源根目录中的 antora.yml 文件提供了 Antora 分配给从位于 modules 文件夹中的标准目录收集的源文件的必需和可选组件版本元数据。

为什么 antora.yml 存储在内容源根目录中？

从每个内容源根目录开始，Antora 寻找一个 antora.yml 文件。当找到 antora.yml 时，它会搜索一个同级 modules 目录，并将其所有子目录和文件视为一个组件版本的一部分。

如果 Antora 在内容源根目录中找不到 antora.yml，它就不会查找 modules 目录或从该位置收集任何文件。这减少了 Antora 处理不属于文档站点的源文件而浪费内存和 CPU 时间的可能性。

antora.yml 文件提供了在目录层次结构中的任何位置存储内容源文件的能力。只要内容源根目录包含一个 antora.yml 文件，您就可以在存储应用程序代码、测试和其他材料的存储库中维护和管理内容源文件。

antora.yml 提供什么信息？

antora.yml 文件被称为组件版本描述符，因为它提供了标识、描述和配置组件版本所需和可选的信息。反过来，这些元数据和配置应用于属于组件版本的所有源文件。

这就是为什么 Antora 可以从多个存储库、目录、分支和标签收集文件，并将它们编译成单个组件版本。Antora 不是根据文件系统或存储库位置处理文件，而是根据组件版本描述符文件为源文件分配的信息转换文件。

antora.yml 文件包含以下必需键：

必需键 描述

name

与 version 一起用于标识组件版本的组件名称。用作资源 ID 中的组件坐标以及组件版本的发布资源的组件 URL 段。

version

与 name 一起用于标识组件版本的版本。用作资源 ID 中的版本坐标以及组件版本的发布资源 URL 段，除非组件版本被定义为无版本。

如果组件版本描述符文件中的 version 键的值是从playbook 中的内容源继承的，则指定 version 键是可选的。如果要自动从 refname 派生值或基于 refname 映射的值，可以在内容源上指定 version 键。

antora.yml 文件还可以包含以下任意可选键：

可选键 描述

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）。