Antora默认UI

这个项目为使用 Antora 生成的文档站点生成默认的 UI 包。它包含 UI 资源(页面模板、CSS、JavaScript、图像等)和一个 Gulp 构建脚本。该构建可用于本地预览 UI (提供实时更新)，或将其打包以供 Antora 站点生成器使用。

本文档解释了如何使用该项目为使用 Antora 生成的文档站点设置、自定义和管理 UI 。读完之后，你就能：

了解如何构建一个 Antora UI 项目。
设置环境以在 UI 项目上工作。
启动预览服务器以直观地查看 UI 。
采用开发工作流来共享和接受 UI 的更改。
为您的文档站点打包一个可供 Antora 使用的 UI 。

文件类型和技术概述

Antora UI 由以下文件类型组成，这些文件类型用于结构化和样式化由 Antora 生成的文档站点页面。

handlebars 页面模板(布局，部分和帮助)
CSS (使用 PostCSS 增强)
JavaScript (UI 脚本)
图像/图形（特定于 UI）
字体
预览 UI 的示例内容(HTML 和 UI 模型)

为了理解 UI 是如何工作的，让我们从研究 UI 使用的主要技术开始。

Handlebars (file extension: .hbs)

Handlebars 是一个“无逻辑”的模板引擎，用于从模板文件创建 HTML 。模板包含占位符（例如，mustache 表达式 {{{page.title}}} ），从模型中注入内容。它们还包含简单的逻辑表达式，用于重复内容或按条件包含内容（例如 {{#each navigation}} ），以及部分内容（例如 {{> header}} ）。

Gulp (script file: gulpfile.js/index.js)

Gulp 是 JavaScript 项目的构建工具。它配置了一组任务，可以用于执行自动化任务，例如编译文件、运行预览服务器或发布版本。

npm (command: npm)

NPM 管理从 npmjs.com 下载的软件包(即软件依赖项)。这个项目使用的软件包括处理编译的库，以及作为 npm 包分发的字体文件等共享资源。npm 是 Node.js 的一部分。

package.json: 这个文件跟踪 npm (或 Yarn )应该获取的依赖项(使用模糊版本描述)。
package-lock.json: 这个文件包含了 npm 解析了哪些依赖项的报告。此信息可确保依赖性解析是可重复的。
node_modules/: npm (或 Yarn )获取的解析依赖项的本地缓存。

PostCSS

该项目不使用 CSS 预处理器，如 Sass 或 LESS 。相反，它依赖于通过一系列后置处理器增强的普通 CSS 。最常见的后处理程序通过添加带有厂商前缀的属性，将较新的 CSS 特性移植到较旧的浏览器中。

UI项目vsUI包

UI 项目由 git 存储库中的源文件组成，为创建 Antora UI 包提供了配方和原材料。它包括构建、源文件、项目文件和依赖项信息。这是您的开发工作空间。

UI 包是可分发的存档文件，提供了预编译（解释、合并和/或最小化）的文件，可以直接在 Antora 中使用。

UI项目存储库结构(默认分支)

您应该将 UI 项目的默认分支视为您的 UI 工作区。它包含用于创建 UI 的配方和原材料，包括构建、源文件、项目文件和依赖项信息。

下面是 UI 项目中文件的结构：

README.adoc
gulpfile.js/
  index.js
  lib/
  tasks/
package.json
package-lock.json
src/
  css/
    base.css
    breadcrumbs.css
    ...
  helpers/
    and.js
    eq.js
    ...
  img/
    back.svg
    caret.svg
    ...
  layouts/
    404.hbs
    default.hbs
  partials/
    article.hbs
    breadcrumbs.hbs
    ...
  js/
    01-navigation.js
    02-fragment-jumper.js
    ...
    vendor/
      highlight.js
preview-src/
  index.html
  ui-model.yml

Gulp 构建用于编译和组装 UI 项目文件到一个 UI 包中。

UI bundle结构(发布)

UI 包是一个可分发的归档文件，它提供了可供 Antora 使用的文件。

当使用 Gulp 构建 UI 项目文件时，它们被组装在 public 目录下。由于生成了 public 目录，因此删除它是安全的。

UI 包的内容类似于 UI 项目的默认分支内容，除了组成 UI 的文件外，该包不包含任何文件。这是 Antora 使用的内容。

css/
  site.css
font/
  ...
helpers/
  and.js
  eq.js
  ...
img/
  back.svg
  caret.svg
  ...
layouts/
  404.hbs
  default.hbs
partials/
  article.hbs
  breadcrumbs.hbs
  ...
js/
  site.js
  vendor/
    highlight.js

其中一些文件已被编译或聚合，例如样式表和 JavaScript 。构建 UI 文件的好处是，可以针对站点中的静态包含对文件进行优化，而不会妨碍 UI 开发。例如，UI 构建可以优化 svg 或向 CSS 添加供应商前缀。由于这些优化只应用于预编译的文件，所以它们不会干扰 web 开发人员的工作流程。

UI编译和生成器使用概述

Antora UI 项目的目的是将 UI 文件组装到一个可重用的发行版中，Antora 可以使用该发行版来组合 HTML 页面及其所需的资产(assets)。

UI bundle 中唯一必需的文件是页面的默认 Handlebars 布局(即 layouts/default.hbs )。如果启用了 404 页面，则还需要 404 页面的 Handlebars 布局（即 layouts/404.hbs ）。

布局文件必须位于 UI 包的 layouts 文件夹中。布局的名称是文件的基名（不包括文件扩展名），例如， layouts/default.hbs 变成了 default 。

layouts/
  404.hbs
  default.hbs

在 UI bundle 中没有其他必需的文件。任何其他文件之所以需要，只是因为它们被布局引用。这些布局可以是生成 HTML（ partial 或 helper ）时使用的布局或 HTML 引用的资源（ CSS 或 JavaScript ），这些资源提供给浏览器使用。Antora 不会将布局、partial 或 helper 复制到生成的站点中。

如果布局查找 partial ，则该 partial 必须位于 partials 目录中。该 partial 的名称是文件的基名（例如，partials/body.hbs 变成了 body ，并用作 > body ）。如果 partial 在文件夹中，则不使用该文件夹的名称作为 partial 名称的一部分。此外，在 helpers 目录中找到的任何 JavaScript 文件都会自动注册为模板 helper 。helper 函数的名称与文件的基名相匹配（例如，helpers/concat.js 变成了 concat ）。

如果 UI 具有布局(layouts)、部分(partials)和帮助(helpers)，那么它的结构应该是这样的：

helpers/
  concat.js
layouts/
  404.hbs
  default.hbs
partials/
  body.hbs

在生产站点中，UI 以静态方式提供服务。但是，UI 的资产以源代码的形式存在于 UI 项目中，以适应开发并简化维护。当 UI 交付给 Antora 管道时，它处于一个中间的预编译状态。具体来说，git 存储库的默认分支包含源形式的文件，而发布用于分发预编译形式的文件。

UI 的编译工作由 UI 项目和 Antora 共同承担。UI 项目使用本地构建来预编译（即解释、合并和/或最小化）文件。预编译文件不受 Antora 内容模型的影响，使得生成器无需处理这个部分。这也允许 UI 得到重复使用。

然后，UI 项目构建将 UI 打包成一个包，Antora 中的 UI Loader 使用该包。Antora 获取包，将其提取到 UI 目录中，并通过将 Antora 的内容模型编织到 Handlebars 模板中来完成编译，以生成页面和辅助数据文件。然后 Antora 将剩余的 UI 资产复制到站点输出中。

现在您已经了解了构成 UI 的文件以及它是如何组装的，让我们来看看如何设置项目，构建 UI 并预览它。