Upgrade Hexo

program-ape

I started this blog with Hexo 3.2.2 back in 2017 and node version was 6. Now Hexo is at 7.0.0 and node are at 20, it’s time to upgrade. As you can imagine, nothing is easy when upgrading software between major versions, not to mention 4 major versions of Hexo and 14 major versions of node. I’m not going to list all the problems I encountered, but I’ll share some of the solutions I found.

First, I made a very clear mistake by trying to upgrade just Hexo and node. A few hours into the job, I realized that so many packages has deprecated and not working with the desired version, it’s better to start from scratch. Luckily I have all the source code of my blog in md files so I don’t need to worry about losing any content.

I started by bootstrapping a new Hexo website using the latest hexo-cli. And then copy all the md files from the old blog to the new one. Everything almost worked as expected from there. I discovered that Hexo now supports github markdown style of inline image via hexo-renderer-marked, which is a big plus. All I need to do is to specify following in _config.yml:

1
2
3
4
post_asset_folder: true
marked:
  prependRoot: true
  postAsset: true

The theme I used previously was deprecated, so I need to switch to a new one. Installing the theme and using it has no surprise.

Previously I used hexo-deploy-cname3 to use custom cname for my blog. This plugin is no longer maintained, so I need to add a CNAME file in source folder directly. This is easy enough but took me a while to figure out.

During the upgrade, I decided to use Github action to automate the site generation and deployment. I have many computers at home, and I’d like to use any one of them to update my blog. One problem I run into often was that different computer has different environment, and the generated site is not the same. Docker can be one solution, but I used it before, this time I’d like to try something new. My setup is not that trivial because I have a source repo that stores all my source code of the blog, and I use hexo-deployer-git to automatically deploy generated site to my public repo ycshao.github.io where the blog is served from. This brought in the complication of ssh authentication in Github action. ChatGPT helped me to figure out a solution to use deployment key and use webfactory/ssh-agent@v0.5.3 to load the key. So I generated a deployment key and added this public key to ycshao.github.io repo. I also added my private key as the deployment secret to my source repo. The final workflow looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
name: hexo deploy

on:
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]

jobs:
  build:

    runs-on: ubuntu-20.04

    strategy:
      matrix:
        node-version: [20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: true
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - name: setup git user
      shell: bash
      run: |
        git config --global user.name "xxxx"
        git config --global user.email "xxxx"
        git config --global init.defaultBranch master
    - run: npm ci
    - run: npm run build --if-present
    - name: Setup SSH Keys
      uses: webfactory/ssh-agent@v0.8.0
      with:
        ssh-private-key: ${{ secrets.DEPLOYMENT }}
    - run: npm run deploy