补充UI
您可以指定补充UI文件来增强UI包。这些文件被统称为补充UI，因为它们补充了UI包提供的文件。
补充UI对于定制现有UI包而无需创建新UI包非常有用。然而，它不应该被用作开发自定义UI包的替代品。相反，它应该用于进行一些小的调整或添加以适应特定环境。一个这样的例子是网站图标。由于网站图标是品牌标识的一部分，您可能希望使用现成的UI包，但是添加自己的网站图标。您可以使用补充UI来实现这个目标。
工作原理
补充UI叠加在加载的UI包文件上。如果补充UI中文件的路径与UI包中文件的路径不匹配，则将该文件添加到UI包中的文件中。如果补充UI中文件的路径与UI包中文件的路径匹配，则来自补充UI的文件将替换UI包中的文件。补充UI中的文件不会被其他方式处理。
supplemental_files键
使用supplemental_files键配置补充UI，该键位于ui类别键下。该键接受包含补充文件的目录路径或虚拟文件映射。目前，这两种值类型是互斥的。
目录
如果supplemental_files键的值是字符串，则Antora会假定该值是目录的路径。该值可以指定为相对或绝对文件系统路径。相对路径将根据以下规则扩展为绝对路径：
-
如果第一个路径段是波浪号（
~），则剩余路径相对于用户的主目录解析。 -
如果第一个路径段是点号（
.），则剩余路径相对于playbook文件的位置解析。 -
如果第一个路径段是波浪号直接跟着加号（
~+），或者不以前述前缀开头，则剩余路径相对于当前工作目录解析。
ui:
supplemental_files: ./supplemental-uiAntora会扫描此目录中的文件并将它们添加到加载的UI包中。假定该目录是UI层次结构的根。因此，UI路径是相对于此目录的文件路径。
假设您想要用自己的内容替换head-meta部分。在playbook文件相对于supplemental-ui/partials/head-meta.hbs位置创建文件。接下来，填充它与HTML和任何您想要包含的可选模板逻辑。
{{#with site.keys.googleSiteVerification}}
<meta name="google-site-verification" content="{{this}}">
{{/with}}Antora现在将使用此部分来替换UI提供的head-meta部分。
虚拟文件
作为目录的替代方案，您可以直接在playbook中将补充UI文件定义为虚拟文件。如果supplemental_files键的值是数组，则Antora会假定每个条目是一个虚拟文件。虚拟文件条目包含两个键，path和contents。path键是UI中文件的相对路径（例如，partials/head-meta.hbs）。内容可以是指定的目录，也可以来自文件系统中的文件。
如果contents键的值是单行并以文件扩展名结尾（例如，.hbs），Antora会假定该值是指定为相对或绝对文件系统路径的文件路径。否则，Antora将使用输入的值作为内容。如果Antora确定该值是文件路径，则会读取文件并将内容分配给虚拟文件。如果省略contents键，Antora将创建一个空文件。
假设您想要用自己的内容替换head-meta部分。您可以在playbook中将其定义为虚拟文件：
ui:
supplemental_files:
- path: partials/head-meta.hbs
contents: |
{{#with site.keys.googleSiteVerification}}
<meta name="google-site-verification" content="{{this}}">
{{/with}}您还可以将内容放在文件中，并从虚拟文件条目中引用它：
ui:
supplemental_files:
- path: partials/head-meta.hbs
contents: ./supplemental-ui/partials/head-meta.hbs如果您只定义了一些小文件，通常可以直接在playbook中定义它们。如果文件较大，或者需要在多个playbook之间共享它们，则最好将它们存储在单独的文件中。
静态文件
默认情况下，由补充UI提供的可发布资产，如图像和JavaScript文件，将发布到UI输出目录。可以配置某些文件发布到发布站点的根目录。这些文件被称为静态文件。静态文件使用UI描述符ui.yml进行标识，补充UI也必须提供该文件。UI描述符是一个配置UI某些方面的YAML文件。
要创建静态文件，首先在补充UI中创建一个文件，通常位于任何标准文件夹之外。一个很好的静态文件示例是位于站点根目录的网站图标favicon.ico。假设您已经将一个网站图标放在supplemental-ui目录中。如果您从路径加载补充UI，请添加一个包含以下内容的ui.yml文件：
static_files:
- favicon.icostatic_files键接受一个字符串数组。每个条目是UI内文件的相对路径（不应以斜杠开头）。Antora将会识别这个文件，看到网站图标是一个静态文件，并将其发布到站点根目录而不是UI输出目录。
如果您将补充UI定义为虚拟文件，您需要为网站图标和ui.yml文件添加一个条目。
ui:
supplemental_files:
- path: favicon.ico
contents: ./supplemental-ui/favicon.ico
- path: ui.yml
contents: |
static_files:
- favicon.ico| 如果UI包含一个ui.yml文件，则在为补充UI重新定义时需要复制其内容。这是因为补充UI中的文件会覆盖UI包提供的文件。 |
尽管补充UI提供了一种方便的方式将静态文件添加到站点中，但您可能希望考虑使用扩展来代替。