Publish to 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文件的方法。

手动创建文件

.nojekyll文件。例如：

$ touch build/site/.nojekyll

使用补充UI

补充UI功能注入文件。为此，在playbook文件中的 ui类别下添加以下 supplemental_files块：

示例1. 使用补充UI添加.nojekyll文件的antora-playbook.yml

ui:
  bundle:
    url: <bundle的url在这里>
  supplemental_files:
  - path: ui.yml
    contents: |
      static_files:
      - .nojekyll
  - path: .nojekyll

ui.yml告诉Antora使用 static_files键将哪些文件提升到站点的根目录（在UI文件夹之外）。第二个文件 .nojekyll将写入到发布站点的根目录。由于缺少 contents键，Antora将创建一个空文件（相当于上面的 touch命令）。

使用 GitHub Actions

.nojekyll文件，因为该操作会为您处理。让我们开始吧！

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

示例2. .github/workflows/publish.yml构建Antora站点并使用GitHub Actions将其部署到GitHub Pages

name: 发布到 GitHub Pages
on:
  push:
    branches: [main]
  # 允许您从操作选项卡手动运行此工作流
  workflow_dispatch:
concurrency:
  group: github-pages
  cancel-in-progress: false
# 设置GITHUB_TOKEN的权限以允许部署到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: 检出存储库
      uses: actions/checkout@v4
    - name: 配置Pages
      uses: actions/configure-pages@v3
    - name: 安装Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
    - name: 安装Antora
      run: npm i antora
    - name: 生成站点
      run: npx antora antora-playbook.yml
    - name: 上传文件
      uses: actions/upload-pages-artifact@v2
      with:
        path: build/site
    - name: 部署到 GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2

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

antora@3.0.3。

Antora Lunr Extension，以在构建站点中加入搜索小部件。首先，您需要更新playbook存储库和UI，以满足Antora Lunr Extension在该项目的 README中描述的最低要求。完成后，返回到GitHub Actions工作流，并配置它在安装Antora时同时安装扩展。结果如示例3所示。

示例3. .github/workflows/publish.yml包含Antora Lunr Extension

name: 发布到 GitHub Pages并包含Lunr搜索扩展
on:
  push:
    branches: [main]
  # 允许您从操作选项卡手动运行此工作流
  workflow_dispatch:
concurrency:
  group: github-pages
  cancel-in-progress: false
# 设置GITHUB_TOKEN的权限以允许部署到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: 检出存储库
      uses: actions/checkout@v4
    - name: 配置Pages
      uses: actions/configure-pages@v3
    - name: 安装Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
    - name: 安装带有Antora Lunr Extension的Antora
      run: npm i antora @antora/lunr-extension
    - name: 生成站点
      run: npx antora antora-playbook.yml
    - name: 上传文件
      uses: actions/upload-pages-artifact@v2
      with:
        path: build/site
    - name: 部署到 GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2

@antora/lunr-extension@1.0.0-alpha.5。

使用自定义域名

您可以使用 Github Pages 的自定义域名来从不同的 URL（而非默认的 <username>.github.io）上提供您的站点。

如果您正在将您的站点使用 GitHub Actions作为源发布，则可以在 GitHub 网页界面的设置页面配置屏幕中配置您的自定义域名。在 CI 工作流程中不需要其他操作。

另一方面，如果您正在从分支（例如 gh-pages）发布您的站点，则需要将自定义域名写入站点根目录下的 CNAME 文件中。为此，请在运行 Antora 后将以下步骤添加到您的 GitHub Actions 工作流程文件（或您正在使用的任何 CI 流水线的等效文件）中。

- name: 创建 CNAME 文件
  run: echo my-domain-name.com > build/site/CNAME

或者，您可以使用补充 UI 来添加 CNAME 文件，类似于之前添加 .nojekyll 文件的方式。

示例 4. 使用补充 UI 添加 CNAME 文件的 antora-playbook.yml

ui:
  bundle:
    url: <bundle-的-url在此处>
  supplemental_files:
  - path: ui.yml
    contents: |
      static_files:
      - CNAME
  - path: CNAME
    contents: |
      my-domain-name.com

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

有关使用自定义域名以及如何激活它的更多信息，请参阅 GitHub 文档中的管理 GitHub Pages 站点的自定义域名。