Set Up a Playbook :: Antora Docs

配置站点属性

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

在文本编辑器或您选择的IDE中打开一个新文件。通常您会将此文件命名为antora-playbook.yml。
在第一行输入site:，然后按Enter键进入下一行。
site:
site键接受一个键值对映射，定义全局站点属性。
title键是site的子级。输入title: ，然后输入将成为站点标题的文本。按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值是属于Component B的index.adoc文件的最新版本的页面ID。为了让Antora使用此页面，您需要告诉Antora在哪里找到属于Component B的源文件。

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

配置站点的内容源

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

在文件的左侧紧贴边缘处输入content:。按Enter键进入下一行。
```
# ...
  start_page: component-b::index.adoc
content:
```
sources键是content的子级。输入sources:，然后按Enter。
# ... start_page: component-b::index.adoc content: sources:
sources键至少需要一个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键上显式设置branches。
让我们添加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键上使用默认分支过滤器，因为main分支中的文件不应发布到站点。相反，您需要告诉Antora它应该从Demo Component B仓库获取哪些分支。

在下一行输入branches: 和一个左方括号（[）。在[内，输入Antora应该获取的每个分支名称。用逗号分隔值。您列出分支名称的顺序无关紧要。在列表末尾，输入一个右方括号（]）。按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对齐。

branches键还接受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包，通过在您之前工作的playbook文件中定义所需的键。

紧靠文件的左侧，键入ui:。按Enter键进入下一行。
```
# ...
    start_path: docs
ui:
```
bundle键是ui的子级。键入bundle:并按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键。

在下一行输入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时，Antora将在playbook中激活fetch或从CLI中下载UI包。

您快完成了！这是到目前为止您已经组装的整个playbook文件。

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

此playbook将使用指定存储库分支的内容文件和指定UI包的UI文件生成名为My Demo Site的站点。

在运行此playbook之前，您需要保存它。playbook文件通常保存为文件名antora-playbook.yml或相关文件名，例如local-antora-playbook.yml，具体取决于使用的上下文。

保存playbook文件后，您就可以运行Antora了。

您也可以从Demo Docs Site存储库获取此playbook。

设置Playbook

配置站点属性

配置站点的内容源

配置您的站点UI包