Assign Attributes to a Site

站点属性

在playbook中声明的属性被称为站点属性。这些属性被设置并且对站点中的所有页面可用（如果未设置，则不可用）。站点中的页面被定义为Antora在单次运行中在playbook中指定的内容源中找到的所有页面。站点属性可以是内置的、自定义的和页面属性。属性优先规则确定站点属性是否可以在更细粒度级别被覆盖。

除了在playbook中全局声明属性外，属性还可以在antora.yml文件中的每个组件版本或直接在页面的页眉中进行定义。但是，当在站点的playbook中硬设置或硬取消设置属性时，它将覆盖组件版本描述符或页面中相同属性的任何后续声明。站点属性也可以从CLI中进行配置。

Playbook文件与组件版本描述符文件

属性在playbook文件和组件版本描述符文件中使用相同的结构和语法进行声明。

playbook是您配置站点、内容源和UI URL的地方。Playbook文件通常在其文件名中包含单词playbook，例如antora-playbook.yml或local-antora-playbook.yml。

组件版本描述符是您配置组件版本的名称、版本、元数据、属性和导航列表的地方。组件版本描述符的文件名始终为antora.yml。

属性键

站点属性在playbook中的attributes键下进行映射。属性键必须设置在asciidoc键下。

示例1. antora-playbook.yml

asciidoc:
  attributes:
    hide-uri-scheme: ''
    page-team: Coco B
    table-caption: ~
    listing-caption: Snippet@

根据属性优先规则，站点属性适用于站点的所有页面并可用。

在playbook中设置属性

每个站点属性都作为一个键值对单独输入在attributes键下的一行中。

示例2. 在playbook中声明属性

asciidoc: (1)
  attributes: (2)
    listing-caption: Snippet (3)
    hide-uri-scheme: '' (4)
    page-team: Coco B (5)
    db: graphical-peaks-pack.db (6)

1	输入`asciidoc`键，后跟冒号（`:`），然后按`Enter`。
2	`attributes`键嵌套在`asciidoc`键下。输入`attributes`，后跟冒号（`:`），然后按`Enter`。
3	站点属性嵌套在`attributes`键下。输入属性的名称，后跟冒号（`:`）。在冒号后按一次`空格`，然后输入属性的值。
4	要设置一个属性而不指定显式值，请在值部分输入两个连续的单引号（`''`）。对于某些内置属性，空值等效于默认值，尽管这取决于属性。尽管在这种情况下通常使用布尔值`true`有效，但AsciiDoc中的属性值是字符串，因此它可能会被强制转换为字符串值`'true'`。
5	要声明自定义页面属性，请键入`page-`和您的属性名称，后跟冒号（`:`）。在冒号后按一次`空格`，然后输入属性的值。
6	这个自定义属性，像前面的三个属性一样，是硬设置的。

示例2中的属性都是硬设置的。 硬设置的站点属性无法从组件版本描述符或页面中被覆盖。默认情况下，当属性被分配一个不用于取消设置属性的值（即false或~）并且不以修饰符结尾（即@）时，属性被视为硬设置。要允许组件版本或页面修改或取消设置站点属性，您需要软设置站点属性。

在playbook中设置的属性是站点范围的，因此对站点中的每个页面都可用。自定义属性的值，例如page-team和db，可以使用AsciiDoc属性引用语法（例如，{page-team}，{db}）在页面中显示。站点属性也可以从另一个站点属性的值中引用，组件版本属性或页面属性。

软设置属性

软设置的站点属性可以从组件版本描述符或页面中被覆盖。在playbook中，通过在值的末尾附加@修饰符来软设置属性。

示例3. 为属性分配软设置优先级

asciidoc:
  attributes:
    page-team: Coco B@ (1)
    hide-uri-scheme: '@' (2)

1	要软设置已分配显式值的属性，请在其值的末尾附加`@`修饰符。
2	要软设置并分配内置属性的默认值，或者在布尔属性的情况下，空字符串值，请输入一个开头的单引号，后跟`@`修饰符，然后是一个闭合的单引号（`'`）。

由于示例3中的站点属性是软设置的，组件版本描述符或页面可以修改它们的值或取消设置它们。

插入另一个属性的值

在playbook中或从CLI设置的任何站点属性的值都可以使用AsciiDoc属性引用（例如，{page-team}）插入到另一个站点属性的值中。

示例4. 引用另一个站点属性值的站点属性

asciidoc:
  attributes:
    page-team: Coco B@
    db: graphical-peaks-pack.db
    test-server: http://localhost:9090/{db}

站点属性还可以在组件版本属性或页面属性的值中引用。

要防止属性引用替换，请在引用前面插入一个反斜杠（例如，\{not-substituted}）。在这种情况下，属性引用将不会被替换，反斜杠将被省略。

在playbook中取消设置属性

在playbook中也可以取消设置站点属性。当为站点属性分配保留的波浪符号（~）值时，站点属性将被硬取消设置。每个站点属性都以键值对的形式输入到attributes键下的单独行中。

示例5. 在playbook中硬取消设置站点属性

asciidoc:
  attributes:
    figure-caption: ~ (1)
    hide-uri-scheme: ~ (2)

~）。在YAML中， ~是 nil的简写， nil是一个保留值，用于硬取消设置站点属性。 ~）时，也会硬取消设置。

1

2

硬取消设置的站点属性无法从组件版本描述符或页面中覆盖。当站点属性被硬取消设置时，其行为被关闭，不会对站点的页面可用。

软取消设置属性

站点的软取消设置属性可以从组件版本描述符或页面中覆盖。在playbook中，通过将其分配给保留值false来软取消设置属性。

示例6. 为属性分配软取消设置优先级

asciidoc:
  attributes:
    figure-caption: false (1)
    hide-uri-scheme: false (2)

false。 false时，布尔属性也会软取消设置。

1

2

由于在示例6中的站点属性是软取消设置的，组件版本描述符或页面可以重置它们。

优先级规则

Antora首先考虑站点playbook中分配的属性的优先级。硬设置和硬取消设置的站点属性不能被组件版本描述符文件或页面更改。但是，软设置和取消设置的站点属性可以从组件版本描述符或页面中覆盖。

硬设置站点属性使用没有尾随@修饰符的字符串值（例如，value或''）可以防止组件版本描述符或页面更改或取消设置属性。
软设置站点属性使用带有尾随@修饰符的字符串值（例如，value@或'@'）允许组件版本描述符或页面更改或取消设置属性。
硬取消设置站点属性使用波浪符号（~）可以防止组件版本描述符或页面设置属性。
软取消设置站点属性使用false值允许组件版本描述符或页面设置属性。

为组件版本分配属性和 Antora中的AsciiDoc属性。

内置站点属性

Antora从playbook文件的一些键中定义内置站点和页面属性。例如，Antora设置内置属性site-title并将其分配给site.title键指定的值。Antora还默认设置一些内置的AsciiDoc属性，例如sectanchors。有关更多信息，请参阅站点和配置属性和内置页面属性。

一些内置的AsciiDoc属性在Antora环境中不适用。这些属性包括data-uri、allow-uri-read、docinfo、linkcss、noheader、nofooter、webfonts和outfilesuffix。设置这些属性要么没有效果，要么可能导致Antora发生故障。其他属性，如imagesdir，由Antora自动设置，无法被覆盖。

为站点分配属性