发布到GitLab页面

GitLab 是一个 DevOps 平台，它提供了将基于 antora 的文档发布到 web 上所需的一切。在本页中，我们将探讨如何使用 GitLab 使用 Antora 发布您的第一个文档站点。

GitLab概览

每个 GitLab 项目都提供代码托管( git 存储库)、持续集成( GitLab CI )和 支持重定向 的静态 web 托管( GitLab Pages )。因此，GitLab 适合从源代码到发布站点端到端管理整个基于 antora 的文档站点。

要使用 GitLab CI/CD 发布 Antora 站点，您需要：

  • 一个剧本(playbook)项目，它作为一个本地 git 存储库启动，存储 Antora 剧本文件。

  • 零个或多个内容项目，每个项目都有一个托管内容文件的 git 存储库。

  • 在 playbook 项目的 git 存储库的根目录中，有一个名为 .gitlab-ci.yml 的文件，它提供了 CI/CD 配置。

在继续之前，我们建议学习核心 CI/CD 概念 以及 GitLab 文档中对 .gitlab-ci.yml文件 的概述。

开始

首先，在 GitLab 上创建一个新项目来托管您的 playbook 项目。按照该页面上的说明将本地 git 存储库推送到 GitLab 。如果您的 playbook 引用其他内容源存储库，请确保将其也推送到 GitLab 。

接下来，您需要配置 CI/CD 。您只需要在 playbook 存储库的默认分支中设置 GitLab CI/CD 。Antora 将自动从 playbook 中声明的其他存储库中获取内容。

我们将从一个基本的 GitLab CI/CD 配置文件开始，该文件使用 Antora Docker 镜像来构建 Antora 网站并将其发布到 GitLab Pages 。

Example 1. Example 1. .gitlab-ci.yml to build and deploy an Antora site
image:
  name: antora/antora
pages:
  stage: deploy
  interruptible: true
  script:
  - antora --fetch --redirect-facility=gitlab --to-dir=public antora-playbook.yml
  artifacts:
    paths:
    - public

将 .gitlab-ci.yml 文件提交到 git 并将其推送到远程存储库。这将触发第一个 CI/CD 流水线。如果流水线成功，则您的网站将在 Pages 设置页面列出的 URL 上可访问。

默认情况下，GitLab Pages 自动启用 使用唯一域名 选项，这会在托管网站的 URL 中添加一个唯一的数字。这很可能不是你想要的。这个 URL 不仅模糊，而且可能会干扰自定义域名的使用。请按照以下步骤进行更正。

  1. 从项目仓库中导航到 Deploy > Pages 菜单选项。

  2. 取消选中 使用唯一域名 选项。

  3. 点击 保存更改。

该 URL 通常遵循以下模式：

https://<group-name>.gitlab.io/<project-name>

即使该项目是私有的，该网站也将公开。

您可以参考 playbook项目 来查看使用 GitLab Pages 构建和发布 Antora 网站的另一个示例，该示例利用了 GitLab CI/CD 的一些附加功能。

定制构建

到目前为止，我们依赖 Antora Docker 镜像在 CI/CD 中运行 Antora 。Antora Docker 镜像仅提供 Antora 核心组件。它不包括任何扩展程序。

虽然使用 Antora Docker 镜像是一种快速启动的方便方式，但我们强烈建议在 playbook 项目中声明站点的依赖关系（或扩展 Docker 镜像）。通过这样做，您可以使构建自包含且可移植。如果您依赖其他包（如 @antora/lunr-extension 和 asciidoctor-kroki）则尤其重要。

假设您在 playbook 项目中有以下 package.json 文件，该文件声明了 Antora 、Antora Lunr扩展 和 Asciidoctor Kroki 的依赖关系。

Example 2. Example 2. package.json
{
  "name": "my-docs-site",
  "description": "My Docs Site",
  "private": true,
  "devDependencies": {
    "antora": "~3.0",
    "@antora/lunr-extension": "1.0.0-alpha.8",
    "asciidoctor-kroki": "0.15.4"
  }
}

首先需要运行 npm i 来生成 package-lock.json 并提交这两个文件。

有了这个配置，您可以修改 GitLab CI/CD 配置，以基于 Antora Docker 使用的 node:16-alpine 基础镜像。然后，您需要在每次构建时获取依赖关系，因为基本镜像不会提供 Antora 。

Example 3. Example 3. .gitlab-ci.yml
image:
  name: node:16-alpine (1)
variables:
  ANTORA_CACHE_DIR: .cache/antora (2)
  NODE_OPTIONS: --max-old-space-size=4096 (3)
before_script:
- npm ci (4)
pages:
  stage: deploy
  interruptible: true
  rules:
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH (5)
  cache:
    paths:
    - .cache (2)
  script:
  - npx antora --fetch --redirect-facility=gitlab antora-playbook.yml (6)
  artifacts:
    paths:
    - public (7)
1 Antora Docker 使用的基础镜像，如果您在本地安装包到 playbook 项目，则可以使用该镜像。
2 在运行之间存储存储库和 UI 包缓存。
3 (可选)增加为 Node.js 保留的内存，以允许 Antora 处理更重的构建。
4 安装 package-lock.js 文件中定义的依赖项。使用 npm ci 而不是 npm i 可以确保依赖的版本在运行之间保持稳定。
5 仅在此存储库的默认分支上运行。
6 使用 npx 调用 Antora ，它将定位并运行安装在项目中的 Antora 命令。--fetch 标志确保 Antora 从以前的运行中保存的缓存中获取更新。
7 公共目录是用于将站点发布到 GitLab Pages 的预定义文件夹。

如果您的任何内容存储库是私有的，您可以定义一个名为 GIT_CREDENTIALS 的 CI/CD 变量，这个变量将保存访问这些存储库所需的凭据。您可以在内容存储库中设置部署令牌，以赋予 playbook 项目中的 CI/CD 流程（因此是 Antora ）对这些存储库的只读访问权限。

如果希望 Antora 在有任何警告或非致命错误时使 CI/CD 流程失败，请向 antora 命令添加 --log-failure-level=warn 。或者，您可以在 playbook 中设置 runtime.log.failure_level 键，使其成为永久设置。