运行Antora生成您的站点

假设：

在本页中，您将学习：

  • 如何运行Antora并生成站点。

Antora演示playbook和内容存储库

您无需设置playbook文件、组件版本或UI来评估Antora。相反，您可以使用Antora演示playbook和内容存储库。

该演示包括一个包含playbook文件和内容存储库（component-a和component-b）的playbook存储库，该playbook引用这些内容存储库。它还使用由默认UI项目生成的UI捆绑包。

一旦您已经安装了Antora，您可以使用演示材料运行Antora来探索其功能。本页上的说明和示例将指导您完成整个过程。

选择一个playbook

为了生成文档站点，Antora需要一个playbook。但首先，您需要创建或选择一个目录，用于存储playbook以及生成的站点文件（假设您使用默认输出配置）。

在本页的示例中，我们将使用演示playbook和内容存储库。

  1. 打开终端并创建一个名为demo-site的新目录。

    ~ $ mkdir demo-site

  2. 切换（cd）到您刚刚创建的目录。

    ~ $ cd demo-site

  3. 使用您喜欢的文本编辑器或IDE，创建一个名为antora-playbook.yml的新playbook文件，并填充以下示例内容。或者，您可以从演示项目存储库下载playbook文件。

    antora-playbook.yml 
    site:
  title: Antora演示站点
  url: https://my-antora-demo-site.org (1)
  start_page: component-b::index.adoc (2)
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
    1 只有在设置了站点url键时才会生成404页面和站点地图文件。只有当站点url键的值为绝对URL时才会生成站点地图文件。
    2 站点start_page键接受与xrefs中使用的资源ID语法相同的语法。

  4. 将playbook保存为antora-playbook.yml，保存在您在步骤1中创建的demo-site目录中。

运行Antora

  1. 要使用默认的Antora站点生成器生成站点，请将antora命令指向您的playbook文件。在终端中，键入：

    demo-site $ antora antora-playbook.yml

    如果Antora已在本地安装，您需要在Antora命令前加上npx：

    demo-site $ npx antora antora-playbook.yml

    Antora将克隆内容存储库。每个存储库的克隆进度将显示在终端中。

    存储库克隆进度 
    [clone] https://gitlab.com/antora/demo/demo-component-a.git [################]
[clone] https://gitlab.com/antora/demo/demo-component-b.git [################]

    克隆完成后，Antora将把AsciiDoc页面转换为可嵌入的HTML，将HTML包装在UI页面模板中，然后将页面组装成一个站点，默认情况下保存在build/site文件夹下。

  2. 当终端中再次出现命令提示符（$）时，Antora生成完成。如果终端是交互式的（TTY），Antora还会打印一条消息，说明站点生成已完成。该消息将包含您可以在本地查看站点的URL。（您可以通过将IS_TTY环境变量设置为true或false来覆盖Antora的TTY检测。）

    如果在生成过程中出现问题，您将在终端中看到错误消息。

    error: 概括了出现问题的消息

    如果此消息未提供足够的信息来解决问题，您可以要求Antora提供更多上下文。要告诉Antora显示导致错误的调用（即堆栈跟踪），请再次运行antora命令，这次使用--stacktrace选项：

    demo-site $ antora --stacktrace antora-playbook.yml

    在寻求帮助时分享此堆栈跟踪。

  3. 切换到站点文件夹（cd）并列出（ls）其中的内容。

    demo-site $ cd build/site/

    在build/site文件夹内运行：

    site $ ls -1

    您应该看到以下文件和目录列表：

    _
404.html
component-a
component-b
index.html
sitemap-component-a.xml
sitemap-component-b.xml
sitemap.xml
    如果在您的playbook中未定义site.url属性，则404页面和站点地图文件将缺失。主站点地图文件实际上是一个站点地图索引。该文件链接到每个组件的站点地图，其中包含各个页面的URL。

    此列表包括您文档站点的入口点，index.html。

  4. 在某些操作系统上，您可以通过在命令行中键入open，然后输入HTML文件的名称来直接打开站点。

    site $ open index.html

    或者，您可以在浏览器中导航到目的地文件夹内的HTML页面。如果您一直在使用演示材料，一旦找到demo-site目录，导航到文件build/site/index.html。

私有git存储库

Antora可以使用HTTPS上的HTTP基本身份验证与私有存储库进行身份验证。请参阅私有存储库身份验证以了解更多信息。

包含大型打包文件的存储库

如果git存储库包含非常大的打包文件（大于2g），Antora可能无法读取。如果出现这种情况，您将收到以下错误：

FATAL (antora) : 无法读取 null 的属性（读取 'slice'）

这个失败是由Antora使用的git客户端（isomorphic-git）的已知限制引起的。这个限制是由Node.js运行时的内存设置中的硬限制造成的。以下是底层错误消息：

RangeError [ERR_FS_FILE_TOO_LARGE]: 文件大小大于 2 GiB

2g是Node.js中的最大缓冲区大小。换句话说，Node.js对其能够读取到内存中的文件大小有一个上限。如果打包文件超过此大小，Node.js和isomorphic-git将会失败。为了读取更大的文件，isomorphic-git将不得不切换到流而不是将整个文件放入缓冲区，如果这是可行的话。

对于本地git存储库，解决方法是配置git，使其限制本地创建的任何打包文件的大小。这可以通过pack.packSizeLimit配置设置来完成。

$ git config pack.packSizeLimit 1g && git gc

您可以在git文档的git-pack-objects帮助页面中找到有关此设置的信息。

请记住，这个解决方法只适用于本地存储库（已经克隆和配置的存储库）。更改本地存储库的打包大小不会改变远程存储库的存储设置。pack.packSizeLimit也需要在git服务器上进行调整，以便git不会尝试通过网络发送过大的打包文件。