设置 Playbook

让我们以 YAML 格式创建一个基本剧本文件。以下各节中的步骤将引导您设置一个剧本，该剧本配置站点标题和URL，从 Demo Component A 和 Demo Component B 存储库获取源文件，并将 Antora 的引用 UI 应用于转换后的页面。

配置您的网站的属性

首先，让我们配置站点的标题和 URL 。

在文本编辑器或您选择的 IDE 中打开一个新文件。通常将此文件命名为 antora-playbook.yml。
在第一行输入 site: ，然后按kbd:[Enter]进入下一行。
```
site:
```
站点键接受定义全局站点属性的键值对的映射。
title 键是 site 的子键。键入 title: ，然后文本将成为您的网站的标题。按kbd:[Enter]。
```
site:
  title: My Demo Site
```
键入 url: ，然后是您网站的基础 url。
```
site:
  title: My Demo Site
  url: https://docs.demo.com
```
为 URL 键指定一个绝对 URL 会激活次要功能，如站点地图。
在下一行，输入 start_page: 和 Antora 用作站点主页的页面ID。
```
site:
  title: My Demo Site
  url: https://docs.demo.com
  start_page: component-b::index.adoc
```
上面示例中的 start_page 值是文件索引最新版本的页ID。为了让 Antora 使用这个页面，您需要告诉 Antora 在哪里可以找到属于组件B的源文件。

在下一节中，让我们定义内容源 url 、分支和开始路径。

配置站点的内容源

Antora 需要知道它应该从哪些 git 存储库、分支和标签中定位和获取源文件，以及不在存储库根中的任何内容源根的位置。让我们在上一节开始的 playbook 文件中定义这些键。

键入 content: 与文件的左侧对齐。按 kbd:[Enter] 键进入下一行。
```
# ...
  start_page: component-b::index.adoc
content:
```
sources 键是 content 的子键。输入 sources: ，按 kbd:[Enter]。
```
# ...
  start_page: component-b::index.adoc
content:
  sources:
```
srouces 键要求至少为一个 url 键分配远程存储库url或文件系统路径。让我们在下一步中将名为 Demo Component A 的远程存储库的 URL 分配给 url。
键入一个连字符( - )，后面跟着一个空格。然后键入 url: 和内容源存储库的 url 。
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git
现在，Antora 可以定位 Demo Component A 存储库了。但它还需要知道应该获取哪些分支和标签。

当 url 键没有设置分支( branches )或标签( tags )键时，默认的分支过滤器将在运行时应用。由于 Demo Component A 存储库只有一个分支，并且该分支的名称( main )属于默认过滤器的参数，因此您不需要在此 url 键上显式设置分支。
让我们添加 Demo Component B 存储库的 URL 。在新行输入 - url: 和存储库的 url 。
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
Demo Component B 存储库使用分支进行版本控制。分支 v1.0 和 v2.0 中的内容源文件已经准备好发布了。但是，您不能在此 url 上使用默认的分支过滤器，因为主分支中的文件不应该发布到站点。相反，您必须告诉 Antora 应该从 Demo Component B 存储库中获取哪些分支。
在下一行，输入 branches: 和左方括号 ([ )。在 [ 中，键入 Antora 应该获取的每个分支名称。值之间用逗号分隔。按什么顺序列出分支名称并不重要。在列表的末尾，键入右方括号( ] )。按 kbd:[Enter]。
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git branches: [v2.0, v1.0]
确保对 branches 进行足够的缩进，以便 url 中的 u 和 branches 中的 b 对齐。

TIP

分支键也接受 shell glob 模式。例如，您可以在 Demo Component B 的 url 键上定义 branches: v* ，以指定 Antora 获取名称为 v1.0 和 v2.0 的分支。

您还没有完成 Demo Component B 存储库的键配置。每个分支中的内容源根不是在存储库的根，而是在 docs 。您需要在 url 上设置 start_path 键，以便 Antora 可以定位内容源根。

输入 start_path: 和仓库根相对路径

# ...
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs

不要在路径中添加前导或尾随斜杠。

现在，您已经准备好配置所需的最后一组键，这些键将告诉 Antora 应该将什么样的 UI 应用于站点。

配置站点的UI包

为了生成一个站点，Antora 需要一个 UI 包。让我们通过在前几节中处理的剧本文件中定义所需的键来告诉 Antora 使用它的引用 UI 包。

对准文件的左侧，键入 ui: 。按 kbd:[Enter] 键进入下一行。
```
# ...
    start_path: docs
ui:
```
bundle 键是 ui 的子节点。输入 bundle: 并按 kbd:[Enter] 键。
```
# ...
    start_path: docs
ui:
  bundle:
```
url 键是 bundle 的子节点。输入 url: ，然后输入 Antora 的引用 UI 包的 url 。
```
# ...
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
```
Antora 的引用 UI 存档会随着时间的推移而变化，但它的 URL 不会，因此您需要激活快照键。

在下一行输入 snapshot:，值为 true 。

# ...
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

当 snapshot 设置为 true 时，只要在 playbook 或 CLI 中激活 fetch , Antora 就会下载 UI bundle 。

你就快完成了!这是到目前为止您组装的整个剧本文件。

site:
  title: My Demo Site
  url: https://docs.demo.com
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

这个剧本将使用来自指定存储库分支的内容文件和来自指定 UI 包的 UI 文件生成一个名为 My Demo site 的站点。

在运行 Antora 之前，你所要做的就是保存它。Playbook 文件通常以文件名 antora-playbook.yml 或相关的文件名保存，如 local-antora-playbook.yml ，这取决于使用它的上下文。

一旦保存剧本文件后，您就可以运行 Antora 了。

TIP: 你也可以从 Demo Docs Site 存储库中获得这个剧本。