如果您只想对 Antora 生成的站点使用默认 UI，请将以下 UI 配置添加到您的 playbook:
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true|
Note
|
snapshot 属性意味着当命令行存在 --fetch 时使用。此配置时必须的，因为对 UI Bundle 的更新将推送到同一 URL。 如果 URL 是唯一的，则不需要此设置。
|
请继续阅读，了解如何自定义您自己的文档的默认 UI。
本节提供了一个基本教程，教你如何设置默认的 UI 项目，并在本地预览它，并将其与 Antora 一起使用。 可以在 docs.antora.org 的文档中找到更全面的教程。
若要预览和捆绑默认 UI，您的计算机上需要以下软件：
其此, 确保你安装了 Node.js (提供 npm).
$ node --version
如果此命令失败并出现错误，则表示您没有安装 Node.js。 如果该命令未报告 Node.js 的 LTS 版本（例如 v10.15.3）， 则表示您没有安装合适的 Node.js 版本。 在本指南中，我们将安装 Node.js 10。
虽然您可以从官方的软件包安装 Node.js，但我们强烈建议您使用 nvm（Node 版本管理器）来管理 Node.js 。 按照 nvm 的安装说明在计算机上设置 nvm。
安装 nvm 后，打开一个新终端并使用以下命令安装 Node.js 10:
$ nvm install 10
您可以使用以下命令切换到此版本的 Node.js:
$ nvm use 10
将 Node.js 10 设置为新的终端的默认值，请输入：
$ nvm alias default 10
安装 Node.js 后，可以继续安装 Gulp CLI。
需要 Gulp 命令行界面 （CLI） 来运行构建。 Gulp CLI 包提供 gulp 命令，该命令可以查看 Gulp 版本:
可以使用以下命令全局安装 Gulp CLI（如果使用 nvm，则解析为用户目录中的某个位置）：
$ npm install -g gulp-cli
通过运行以下命令，验证 Gulp CLI 是否已安装并在 PATH 上:
$ gulp --version
如果您使用的时 Yarn 安装全局包，请改为运行以下命令：:
$ yarn global add gulp-cli
或者，您可以使用 gulp 命令，此命令由项目的依赖项安装的
$ $(npm bin)/gulp --version
好了，现在可以克隆并生成 UI 项目。.
使用 git 克隆默认 UI 项目：:
$ git clone https://github.com/jcohy/antora-ui-jcohy.git && cd "`basename $_`"
上面的示例克隆项目，并进入项目目录。
使用 npm 在安装项目的依赖。 在终端中，执行以下命令：
$ npm install
此命令将 package.json 中列出的依赖项安装到项目内的 node_modules/ 文件夹中。 此文件夹不会包含在 UI bundle 中，也不应提交到源代码管理存储库。
|
Tip
|
如果您更喜欢使用 Yarn 安装软件包，请改为运行以下命令: $ yarn |
默认 UI 项目配置为脱机预览。 preview-src/ 文件夹中的文件提供了示例内容，可用于查看 UI 的运行情况。 在此文件夹中，您将主要找到用 AsciiDoc 编写的页面。 这些页面提供了来自真实站点的内容的代表性示例。
若要生成 UI 并在本地 Web 服务器中预览它，请运行以下命令: preview
$ gulp preview
你将看到此命令的输出中列出了一个 URL:
[12:00:00] Starting server... [12:00:00] Server started http://localhost:5252 [12:00:00] Running server
点击此链接预览.
运行 preview:build 命令时，对源文件所做的任何更改都将立即反映在浏览器中。 其工作原理是监视项目的更改，在检测到更改时运行任务，并将更新发送到浏览器。
Ctrl+C 停止预览。
如果需要打包 UI，以便可以使用它在本地生成文档站点，请运行以下命令:
$ gulp bundle
如果 lint 报告了任何错误，则需要修复它们。
命令成功完成后，UI bundle 将在 build/ui-bundle.zip. 中。 您可以使用 --ui-bundle-url 命令行选项将 Antora 指向此包。
如果您正在预览，并且想要在不导致预览中断的情况下进行打包，请使用：
$ gulp bundle:pack
UI bundle 将再次在打包在 build/ui-bundle.zip.
该版本将所有 CSS 和客户端 JavaScript 分别合并到组合文件（site.css 和 site.js）中，以减小包的大小。https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map[Source maps] 将这些组合文件与其原始文件相关联。
这种 “source mapping” 是通过生成其他映射文件来实现的。 这些映射文件与生成文件夹中的组合文件相邻。 它们提供的映射允许调试器显示原始源代码，而不是模糊处理的文件，这是调试的基本工具。
在预览模式下，源映射会自动启用，因此您无需执行任何操作即可使用它们。 如果需要在包中包含源映射，可以设置 SOURCEMAPS 环境变量，为在运行 bundle 命令时执行此操作
$ SOURCEMAPS=true gulp bundle
在这种情况下，包将包含源映射，这些映射可用于调试生产站点。
Copyright © 2017-present OpenDevise Inc. and the Antora Project.
Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE to find the full license text.
Development of Antora is led and sponsored by OpenDevise Inc.
UI 显示相关文档的列表，可以使用两个属性筛选该文档：
-
page-related-doc-categories - 要包含在相关文档中的类别
-
page-related-doc-projects - 要包含在相关文档中的项目 ID
有关有效类别和 ID 的完整列表，请查看 related_projects.js
该配置通常在 antora-playbook.yml 的 asciidoc attributes 部分中指定：
asciidoc:
attributes:
# Include the projects with the security category
page-related-doc-categories: security
# Include the projects with ids framework and graphql
page-related-doc-projects: framework,graphql相关文档链接到 All Docs… 页面。 要包含此资源，请确保 antora-extensions 使用的是 1.7.0+， 并且包含 Static Page Extension。