使用 Github Actions 在 Github Pages 上部署 Hexo

---

前言

尽管在 2022 年的某个时间点后，我就不再继续写博客了，未完成文章的草稿也放在那里不去处理了。一方面是因为已经和所谓 Competitive Programming 彻底说再见，也可能是单纯地变懒了，失去了努力的动力。在 2024 年年底，我突然心血来潮，决定使用 Github Actions 来完善先前使用 Hexo 写博客的工作流，在半年后又突发奇想，基于回忆将改变的过程记录了下来。

Hexo、管理主题的方法和 LaTeX 的支持

Hexo 作为静态网站生成器，能够做的工作包括将 Markdown 格式的文本转换为 HTML 之类浏览器认识的东西，并支持主题来让大家的博客看起来不一样。考虑到我对前端一窍不通、同时也没有什么设计能力和审美水平，在 2019 年我就决心使用 hexo-theme-chan。这个主题已经多年没有更新，好处是原先的代码并不复杂，在没有 LLM 的时代，一个没有前端经验的高中生都可以做简单的修改，同时不用担心上游再引入什么更新。

为了便于后续自动化部署使用修改后的主题，我 fork 了 hexo-theme-chan。后续只需新建一个 private repo 记录 hexo 需要的各项文件，在 themes/ 目录下使用 git submodule 使用 fork 后的版本就好了。为了避免在 submodule 中引入修改，我选择额外记录一个 themes/config.yml 然后在部署时额外做一步替换。当然也可以直接修改 themes 里的 _config.yml 然后在原来的 repo 中记录修改。此处怎么做都可以，只要能够用 Github Actions 描述这一过程实现自动部署就好了。

之前选择的 LaTeX 支持方式是使用 MathJax，需要将渲染引擎由原先的 hexo-renderer-marked 换成 hexo-renderer-kramed。后者依赖 kramed，已经多年没有更新，好在多年以来使用的人足够多（时至今日，在搜索引擎上搜索“Hexo 支持 LaTeX”还能够找到），对于支持 LaTeX 这种比较普遍的需求，即使有问题大家也已经有了相对应的解决方法。比如说，kramed 支持形同 _italic_ 的斜体语法，但和 LaTeX 中的下标不太兼容，使用 $ 包裹的公式中下标使用的 _ 会被错误地渲染为斜体。

那怎么办呢？在互联网中流行的做法是砍掉 Markdown 中使用下划线 _ 表示斜体的语法，在 kramed 中做对应改动。此前只在本地使用 hexo，直接在 node_modules 里做修改也不是不能跑。不过如果希望自动化部署、接着在 repo 中传个 node_modules 中有点过于幽默了，所以干脆 fork 一份自己改，再修改 package.json 就好了。

{
  ...
  "dependencies": {
    ...
  },
  "overrides": {
    "kramed": "git+http://github.com/DepletedPrism/kramed.git#master"
  }
}

使用 MathJax 的手段是在页面引入一段 JavaScript 代码，负责公式的渲染。从使用 MathJax 开始，我时不时就会遇到插入的这段 JavaScript 代码消失的情况，但重新生成就又回来了，原因不明。这就是我一直想实现自动部署的原因，希望能够以此解决这个问题。可惜的是，在我大量写文章的那段时间并没有花时间处理这件事，但如果在实现后反而不更新博客的话，就更加可惜了。

使用 Github Actions 部署 Hexo 到 Github Pages

在得到 Github Actions 脚本后剩余的工作只有生成一个有修改 repo 权限的 token。我的建议是 token 距离报废的时间尽量拉长一点，因为即使有安全洁癖，我体感认为洁癖程度会随着续 token 的次数增加而不断减少，那还不如一开始就把时间拉到最长，方便我放手不管。

对应 YAML 文件的名字没有什么所谓，不同的是路径中 workflows 里的 s 少了 Github 就不认识了…

# .github/workflows/hexo-depoly.yml
name: Deploy Hexo to GitHub Pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout blog source
        uses: actions/checkout@v4
        with:
          path: blog
          submodules: true # 因为选择使用 submodule 管理 theme，所以要指定

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Install dependencies
        run: |
          npm install
        working-directory: ./blog

      - name: Install Hexo CLI
        run: |
          npm install -g hexo-cli
        working-directory: ./blog


      # 我选择的方法是复制 themes/_config.yml 到对应的主题中
      - name: Generate static pages
        run: |
          cp -f themes/_config.yml themes/your-hexo-theme/_config.yml
          hexo generate
        working-directory: ./blog

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          publish_dir: ./blog/public
          external_repository: your-repo/your-repo.github.io # 对应 Github Pages 的 repo
          publish_branch: master

后记

最近 CODING 宣布停止提供服务，重复发了好多次邮件。由于众所周知的网络原因，在最开始学 OI 的时候，我选择 CODING 作为 git 托管记录自己写过的题和看到的代码模板。当然过一阵子就换了，原先的仓库也就没有再管过，直到现在。下载来看的话，所有文件加起来不过几十 KB，README 里写的还是“一个蒟蒻写出来但是没有 AC 的代码”和“还是中文看着舒服”。不过，到最后这些代码有没有 AC 我早就不清楚了，英文界面对于现在的我而言也不算什么大的障碍了。但是，我的青春就在这些旧代码、旧文章里，变成历史的尘埃了吧。

参考资料

• 让 Hexo 搭建的博客支持 LaTeX
• 利用 GitHub Actions 实现自动化部署 Hexo 到 Github Pages - Gavin Zhou

---