什么是 antora.yml

antora.yml 是一个提供两个关键功能的配置文件。

  1. 存在内容源根目录下的 antora.yml 文件向 Antora 发出信号，它应该找到包含属于组件版本的源文件的兄弟模块目录。

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

什么是存储在内容源根的 antora.yml

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

如果 Antora 在内容源根目录下找不到 Antora.yml ，它不会查找模块目录或从该位置收集任何文件。这最大限度地减少了 Antora 浪费内存和CPU时间来处理不属于文档站点的源文件的可能性。

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

antora.yml 提供的信息是什么

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

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

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

必需的键 描述

name

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

version

版本与名称(name)一起使用，用于标识组件版本。用作资源 id 中的版本坐标，以及组件版本发布的资源 url 的版本段，除非组件版本被定义为未版本化。

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

一个 antora.yml 文件还可以包含以下任何可选键：

可选键 描述

asciidoc.attributes

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

display_version

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

nav

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

prerelease

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

start_page

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

title

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