添加静态文件

静态 UI 文件是直接添加到站点的 UI 提供的任何文件。静态文件的一个常见示例是图标图像。添加静态文件的一种方法是使用补充 UI ，它在您的 Antora 剧本中定义。本文解释了如何使用 UI 包来添加静态文件。

设置静态文件文件夹

首先需要一个地方来存储 UI 项目中的静态文件。为此，让我们在 src 下创建一个名为 static 的文件夹。

mkdir src/static

您可以将静态文件，例如，favicon.ico 添加到此文件夹中。UI 构建将在此文件夹中添加文件到 UI 包的根目录中，从路径中删除静态文件夹前缀。

Antora 自动将包中的静态文件传递到 UI 输出文件夹中（默认为 ），忽略任何隐藏文件（即以点开头的文件）。静态文件是未被指定为布局、部分或助手的任何文件。这意味着我们的 favicon 图像文件最终将位于路径 /favicon.ico 。

Contents of site

_/
  favicon.ico
  css/
    site.css
  ...
sitemap.xml
...

如果这是您想要文件的位置，那么您不需要做任何其他事情。否则，您可以选择将选定的静态文件提升到站点根目录。

如果希望从 UI 输出文件夹中提升某些静态文件，则需要标识它们。Antora 查找一个名为 ui.yml 的文件。UI 描述符，放在 UI 包中，用来配置 UI 的行为。

首先，在 UI 项目中创建文件 src/ui.yml 。如果存在，UI 构建将将此文件复制到 UI 包的根目录中。

此文件不需要任何必需的键。我们感兴趣的键是 static_files 。此键通过 UI 包中的相对路径标识应该从 UI 输出文件夹提升到站点根目录的文件。文件必须指定为一个数组，其中每个条目都是相对路径或路径通配符。与其他静态文件不同，提升的静态文件可以以点开头。

以下是如何配置 UI 描述符以将 favicon 图像文件提升到站点根目录的方法。

src/ui.yml

static_files:
- favicon.ico

如果您有多个具有不同文件扩展名的 favicon 文件，您可以使用 glob 来匹配它们。

src/ui.yml

static_files:
- favicon*

有了这个配置，Antora 将从 UI 包中读取 favicon 图像，并将其复制到站点的根目录。

Contents of site

_/
  css/
    site.css
  ...
favicon.ico
sitemap.xml
...

现在让我们看看如何使用静态文件。

通常，当您向站点添加静态文件时，您需要在某个位置引用它们。在 favicon 图像的情况下，它必须在 HTML 页面的 <head> 中引用。如果您正在引用提升的静态文件，则将使用前缀 {{{siteRootPath}}} 。否则，您将使用前缀 {{{uiRootPath}}} 。

让我们更新 src/partials/head-icons.hbs 部分，以引用站点根目录的 favicon 图像。

src/partials/head-icons.hbs

    <link rel="icon" href="{{{siteRootPath}}}/favicon.ico" type="image/x-icon">

用 gulp bundle 重新构建 UI 。现在您应该看到您的站点有一个由 UI 包提供的 favicon 图像。