玩转云服务（3）：使用 Hugo + docsy + Github Actions + Github Pages 创建项目文档

文中项目文档的网址：https://github.com/Eterance/Pymaidol-Docs

2023.09.16更新：更好用的文档生成器：玩转云服务（6）：使用 Docusaurus 创建项目文档

Windows 本地安装 Hugo

https://gohugo.io/installation/windows/

首先按照顺序安装前置需求： Git, Go, Chocolatey, saas。

然后使用 Chocolatey 安装 Hugo：

choco install hugo-extended

然后下载安装 node.js（docsy 主题需要）：https://nodejs.org/en/download

建立文档项目

CMD建立空的 Hugo 站点并安装 docsy 依赖：（pymaidol-docs 修改成自己的项目名称）

hugo new site pymaidol-docs
cd pymaidol-docs
git init

npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
npm install -D postcss

然后自行添加一个 .gitignore 文件。内容是：（来自 https://github.com/google/docsy/blob/main/.gitignore）

/public
resources/
node_modules/
# package-lock.json 要一起上传，不然 CI 会出错
# https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
#package-lock.json
.hugo_build.lock

然后推送到 Github 上。

项目 Github Pages 设置

完善网站内容 & 本地运行测试网站

省略，自行借鉴我的文档项目。

hugo 运行的命令：

hugo server

Github Action + Github Pages 线上部署

在根目录下新建文件夹及文件：.github/workflows/hugo-docsy-gh-pages.yml，并输入以下内容：

name: Deploy Hugo site with Docsy to Pages
# https://github.com/peaceiris/actions-hugo#%EF%B8%8F-workflow-for-autoprefixer-and-postcss-cli

# blend some part of official hugo deploy action:
# https://gohugo.io/hosting-and-deployment/hosting-on-github/#build-hugo-with-github-action

on:
  push:
    branches:
      - main  # Set a branch to deploy

  # 官方部分
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

  # 不需要提交一次PR就触发CI
  #pull_request:

# 官方部分
# 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-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
      
      # 官方部分
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.110.0'
          extended: true

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
          # The action defaults to search for the dependency file (package-lock.json,
          # npm-shrinkwrap.json or yarn.lock) in the repository root, and uses its
          # hash as a part of the cache key.
          # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
          cache-dependency-path: '**/package-lock.json'

      - run: npm ci
      
      # 官方部分
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  # 官方部分
  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

根目录下的 go.mod 文件修改为：

module github.com/Eterance/pymaidol-docs

go 1.21

require github.com/google/docsy v0.7.1 // indirect

原本是 go 1.21.0，但是会导致 Github Actions 报错：

然后推送，就会触发CI（没触发就到项目 Action 手动点一下）。