部署到 GitHub Pages

仅使用 Hugo 将 OINK 站点部署到 GitHub Pages。

如果源码托管在 GitHub，只需一份 Actions 工作流，就能通过 GitHub Pages 构建并发布站点。消费站点需要 Hugo Extended，但不需要 Node.js、npm、PostCSS，也不需要生成专门的部署分支。

项目站点的 URL 形如 https://<OWNER>.github.io/<REPOSITORY>/；用户和组织站点使用 https://<OWNER>.github.io/。GitHub Pages 也支持自定义域名。

准备代码仓库

把完整的站点源码推送到 GitHub，并确认在仓库根目录执行以下命令能够成功：

hugo --gc --minify

将站点的 baseURL 设为生产 URL，或者在工作流中通过 Hugo 的 --baseURL 参数传入 Pages URL。项目站点必须包含仓库路径，否则 CSS、JavaScript 和其他资源会从错误的位置解析。

添加 Pages 工作流

创建 .github/workflows/pages.yml，内容如下。请让 HUGO_VERSION 始终与主题已经验证的版本保持一致。

name: Deploy Hugo site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

env:
  GO_VERSION: 1.25.5
  HUGO_VERSION: 0.164.0

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          submodules: recursive
      - uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
      - name: Install Hugo Extended
        run: |
          curl -L -o hugo.deb \
            "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
          sudo dpkg -i hugo.deb
      - uses: actions/configure-pages@v6
        id: pages
      - name: Build
        run: >-
          hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
      - uses: actions/upload-pages-artifact@v5
        with:
          path: public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

如果通过 Git submodule 安装主题，submodules: recursive 会在 Hugo 运行前检出主题。如果使用完整离线归档，则可以把相邻的 theme/ 目录提交到仓库，或在构建输入中恢复该目录。

启用 GitHub Pages

在仓库设置中打开 Pages。在 Build and deployment 下，将 Source 设为 GitHub Actions。把工作流推送到 main，然后在仓库的 Actions 标签页中查看第一次运行。

工作流只上传生成的 public/ 目录，并通过 Pages 部署 API 发布，不会维护 gh-pages 分支。

有关其他身份验证、域名和权限选项，请参阅 GitHub 的 Pages 文档和 Hugo 的 GitHub 托管指南。