chore: upgrade html-proofer to 5.x, switch to ruby-china gem source, use Ruby 4.0 in CI

Author: puppylpg

.github/workflows/pages-deploy.yml

@@ -4,20 +4,21 @@ on:
     branches:
       - main
       - master
+    # 纯文档改动不触发部署
     paths-ignore:
       - .gitignore
       - README.md
       - LICENSE
 
-  # Allows you to run this workflow manually from the Actions tab
+  # 允许在 Actions 页面手动点按钮触发
   workflow_dispatch:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
+  pages: write      # 发布到 GitHub Pages 必须
+  id-token: write   # actions/deploy-pages 的 OIDC 身份验证必须
 
-# Allow one concurrent deployment
+# 同一时间只跑一个部署；连续 push 时取消旧的，只跑最新的
 concurrency:
   group: "pages"
   cancel-in-progress: true
@@ -30,29 +31,41 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          # 完整 git 历史，不做浅克隆
+          # _plugins/posts-lastmod-hook.rb 需要读历史来注入 last_modified_at
           fetch-depth: 0
           # submodules: true
           # If using the 'assets' git submodule from Chirpy Starter, uncomment above
           # (See: https://github.com/cotes2020/chirpy-starter/tree/main/assets)
 
+      # 配置 GitHub Pages 环境，主要输出 base_path
+      # 如果站点不在根路径（如 /repo-name/），后续构建需要用到
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3
 
+      # 安装 Ruby；bundler-cache: true 自动跑 bundle install 并缓存 gems
+      # Gemfile.lock 不变时直接用缓存，加速构建
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.2.2
+          ruby-version: 4.0
           bundler-cache: true
 
+      # 构建前预处理：把 tags/categories 转小写，清理 TOC
       - name: puppylpg's scripts
         run: bin/lower_tag.sh && bin/clean_toc.sh
 
+      # 核心构建步骤，用 Gemfile.lock 里的 Jekyll（目前 4.4.1）生成静态文件
+      # JEKYLL_ENV=production 开启 analytics、comments 等生产环境功能
       - name: Build site
         run: bundle exec jekyll b -d "_site${{ steps.pages.outputs.base_path }}"
         env:
           JEKYLL_ENV: "production"
 
+      # 检查生成的 HTML：链接有效性、图片存在等；失败则阻止部署
+      # --disable-external: 跳过外链检查（太慢）
+      # --ignore-files "/tutorials/": tutorials 有残留坏链，清理前先跳过
       - name: Test site
         run: |
           bundle exec htmlproofer _site \
@@ -61,6 +74,8 @@ jobs:
             \-\-ignore-files "/tutorials/" \
             \-\-ignore-urls "/^http:\/\/127.0.0.1/,/^http:\/\/0.0.0.0/,/^http:\/\/localhost/"
 
+      # 把 _site/ 打包上传为 artifact，供 deploy job 使用
+      # 两个 job 不共享文件系统，只能通过 artifact 传递产物
       - name: Upload site artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -71,8 +86,10 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: build   # build job 成功才执行，失败则跳过
     steps:
+      # 把 build job 上传的静态文件发布到 GitHub Pages
+      # GitHub Pages 在这里只做托管，Jekyll 构建早已在 build job 完成
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4