发布到GitHub页面

Antora 旨在创建可以在任何地方运行的站点，无论是在静态 web 主机上还是在本地文件系统上。然而，一些主机提供的功能会干扰 Antora 的输出。GitHub Pages 就是其中之一。

Jekyll和下划线文件

默认情况下，GitHub Pages 通过另一个名为 Jekyll 的静态站点生成器运行所有文件(即使您的存储库没有设置为使用 Jekyll )。由于 Antora 已经生成了一个现成的站点，因此绝对不需要执行此步骤。

Jekyll 的一个讨人厌的副作用是删除所有以下划线（_）开头的文件。为什么这是个问题呢？Antora 默认将 UI 文件放在一个名为 _ 的文件夹中，并将图像放在名为 _images 的文件夹中。当 Jekyll 进行处理时，它会清除这些文件夹。结果导致你得不到任何 UI 和图像。

.nojekyll

幸运的是，有一种方法可以禁用 GitHub Pages 的这个 “功能”。解决方案是在发布网站的根目录（即你在 playbook 中配置的输出目录）添加一个 .nojekyll 文件。

gh-pages 分支根目录中的 .nojekyll 文件告诉 GitHub Pages 不要通过 Jekyll 运行已发布的文件。结果是您使用 Antora 制作的网站将按预期运行。

接下来，我们将讨论两种在运行 Antora 时创建 .nojekyll 文件的方法。

手动修改文件

一种添加此文件的方法是在 Antora 运行后，但在将文件提交到 GitHub Pages 之前，在输出目录中创建 .nojekyll 文件。例如：

touch build/site/.nojekyllbash

幸运的是，有办法做到这一点，而不必运行单独的命令。

使用补充UI

为了避免需要额外的命令，另一种方法是使用 Antora 的补充 UI 功能来注入该文件。为此，请在播放书文件的 ui 类别下添加以下 supplemental_files 块：

Example 1. Example 1. antora-playbook.yml that adds .nojekyll file using supplemental UI

ui:
  bundle:
    url: <url-of-bundle-goes-here>
  supplemental_files:
  - path: ui.yml
    contents: |
      static_files:
      - .nojekyll
  - path: .nojekyllyaml

该配置从内存中定义文件。第一个文件 ui.yml 告诉 Antora 使用 static_files 键将哪些文件提升到网站的根目录（UI 文件夹外）。第二个文件 .nojekyll 将被写入已发布网站的根目录。由于缺少 contents 键，Antora 会创建一个空文件（相当于上面的 touch 命令）。

使用GitHub动作

如果你的 playbook 仓库托管在 GitHub 上，你可以配置一个 GitHub Actions 工作流来构建和发布你的站点到 GitHub Pages。使用 GitHub Actions 的好处有两个方面。首先，你不必担心将已发布的文件复制到 gh-pages 分支进行发布。其次，你也不必担心 .nojekyll 文件，因为这个动作会为你处理它。让我们开始吧！

示例 2 展示了一个使用最新稳定版本 Antora 的 GitHub Actions 工作流示例，用于构建和发布你的站点到 GitHub Pages。该工作流假设你的 playbook 仓库的默认分支名称为 main，playbook 文件的名称为 antora-playbook.yml，并且 Antora 被配置为将文件发布到 build/site 目录。如果你的站点使用不同的设置，你需要相应地更新工作流文件中的值。

name: Publish to GitHub Pages
on:
  push:
    branches: [main]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
concurrency:
  group: github-pages
  cancel-in-progress: false
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
    - name: Configure Pages
      uses: actions/configure-pages@v3
    - name: Install Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
    - name: Install Antora
      run: npm i antora
    - name: Generate Site
      run: npx antora antora-playbook.yml
    - name: Upload Artifacts
      uses: actions/upload-pages-artifact@v2
      with:
        path: build/site
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2yaml

正如示例 2 所示，你可以直接在工作流中安装和调用 Antora。这个工作流安装了特定版本的 Antora（包括 CLI 和站点生成器包），然后在工作流中使用 Antora CLI。接着，工作流使用 peaceiris/actions-gh-pages 动作将站点及所需的 .nojekyll 文件发布到 GitHub Pages。

要安装和使用不同版本的 Antora，可以在包名后附加版本号，例如 antora@3.0.3。

现在，让我们更进一步，添加 Antora Lunr 扩展，以在构建的站点中集成搜索小部件。首先，你需要更新 playbook 仓库和 UI，以满足 Antora Lunr 扩展的最低要求，具体内容可参考该项目的 README。完成后，返回 GitHub Actions 工作流，并配置它以在安装 Antora 的同时安装该扩展。结果如示例 3 所示。

Example 2. Example 3. .github/workflows/publish.yml includes the Antora Lunr Extension

name: Publish to GitHub Pages with Lunr Search Extension
on:
  push:
    branches: [main]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
concurrency:
  group: github-pages
  cancel-in-progress: false
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
    - name: Configure Pages
      uses: actions/configure-pages@v3
    - name: Install Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
    - name: Install Antora with the Antora Lunr Extension
      run: npm i antora @antora/lunr-extension
    - name: Generate Site
      run: npx antora antora-playbook.yml
    - name: Upload Artifacts
      uses: actions/upload-pages-artifact@v2
      with:
        path: build/site
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2yaml

要安装和使用不同版本的 Antora Lunr 扩展，可以在包名后附加版本号，例如 @antora/lunr-extension@1.0.0-alpha.5。

使用一个自定义域名

你可以使用 GitHub Pages 自定义域名，将网站托管在与默认的 <username>.github.io 不同的 URL 上。

如果你是通过 GitHub Actions 发布网站作为源，那么可以在 GitHub 网站界面的 Settings > Pages 配置屏幕中配置你的自定义域名。在 CI 工作流中不需要其他操作。

另一方面，如果你是从某个分支（例如 gh-pages）发布网站，那么你需要在网站根目录下写入一个 CNAME 文件以指定自定义域名。为此，在运行 Antora 之后，将以下步骤添加到你的 GitHub Actions 工作流文件中（或你所使用的其他 CI 流水线的等效步骤）。

- name: Create CNAME file
  run: echo my-domain-name.com > build/site/CNAMEyaml

另外，你可以使用补充 UI 来添加 CNAME 文件，类似于之前添加 .nojekyll 文件的方法。

Example 3. Example 4. antora-playbook.yml that adds CNAME file using supplemental UI

ui:
  bundle:
    url: <url-of-bundle-goes-here>
  supplemental_files:
  - path: ui.yml
    contents: |
      static_files:
      - CNAME
  - path: CNAME
    contents: |
      my-domain-name.comyaml

该配置从内存中定义文件。第一个文件 ui.yml 告诉 Antora 使用 static_files 键将哪些文件提升到网站的根目录（UI 文件夹外）。第二个文件 CNAME 将被写入已发布网站的根目录，并包含自定义域名，这是 GitHub Pages 在从分支发布时所需的。这个方法的好处是它不需要在 CI 工作流中增加额外的步骤。

有关使用自定义域名及其激活方法的更多信息，请参考 GitHub 文档中的管理 GitHub Pages 网站的自定义域名。