maupassant-hexo with github action

照着教程来：大道至简——Hexo 简洁主题推荐 | 屠·城

博客配置注意

  1. self_search

    1. set self_search: true in maupassant __config.yml
    2. npm instal hexo-generator-search --save

  2. word counter

    1. set wordcount: true in maupassant __config.yml
    2. npm install hexo-wordcount --save

    If you want to display the word counter and the reading time expected to spend of each post please set the value to true, and you must have hexo-wordcount installed.

  3. add sitemap for spider

    1. npm install hexo-generator-sitemap --save

    2. add the following line to hexo __config.yml

    1
    2
    3
    4
    5
    Plugins:
    - hexo-generator-sitemap

    sitemap:
        path: sitemap.xml

  4. 增加 google analysis Universal Analytics property 的 id 是 UA-xxx, 而 Google Analytics 4 的 id 是 G-xx Universal Analytics property 已经被 Google Analytics 4 更新迭代替换了。

  5. 提交 google search 收录

    打开 https://search.google.com/search-console，因为本次部署并未使用自定义域名， github page 也没有 DNS 可以额外设置，因此选择 URL 验证：

    1. https://realyee.github.io/

      选择 HTML 文件下载方式，然后将 HTML 问价放到 hexo 根目录的 source 文件夹中，并在该 HTML 文件开头加上以下四行，防止 hexo 渲染。

      1
      2
      3
      layout: false
      ---

    2. https://realyee.github.io/blog/

      之前添加过 google analysis， maupassant 主题在网页加入了 gtag 之类的，直接验证成功，然后提交 sitemap 即可。

  6. 任意一个 github 仓库都可以开启 github pages 功能，可以考虑将学术主页部署在 github page 主页，将博客部署在 blog 项中

    搭建 hexo-theme-academia 主题学术主页, 在 hexo 的 __config.yml 中的 index_generator 的 path 加上 /home 来展示主页,然后在 source 目录下创建 home/index.md, 注意要在其 front-matter 中加入 permalink: index.html

    1
    2
    3
    4
    index_generator:
    path: "/home"
    per_page: 10
    order_by: -date

    这样的话，自己一些 web 项目也可以开启 Github page 映射到网络上来。

  7. 使用 git 部署 在两个 hexo 仓库目录下都执行 npm install --save hexo-deployer-git

  8. mathjax 渲染多行公式失败，使用 pandoc 正确渲染多行 MathJax 公式

    Hexo 官方的默认渲染插件 hexo-theme-marked 虽然能满足大部分渲染要求，但也存在着以下不足（针对 v4.0.0 版本）：

    • 不支持 Github-Flavoured-Markdown 的表情：😄
    • 不支持上下脚标
    • 脚注不支持
    • 目录[TOC]不被支持
    • 不支持 MathJax 数学公式换行

    卸载 Hexo 默认渲染插件：npm uninstall hexo-renderer-marked --save 安装 pandoc 渲染插件：npm install hexo-renderer-pandoc --save 注意：需要安装 pandoc，否则会报错

    1
    2
    wget -c https://github.com/jgm/pandoc/releases/download/3.1.6/pandoc-3.1.6-1-amd64.deb
    sudo dpkg -i pandoc-3.1.6-1-amd64.deb

    另一款针对 hexo 的 markdown 渲染器（math 方面插件支持）：hexo-renderer-markdown-it，先试着上面的 pandoc 不行再试这个，😄。

Github action 自动化部署

效果：只需要 commit 源文件，Github action 自动化便会自动部署更新网页。

首先，重述一下我的博客与仓库：realyee.github.io 仓库作为学术主页，开启 page 服务；blog 仓库作为博客主页，开启 page 服务，目录为 realyee.github.io/blog。新建 academic_source，blog_source 私人仓库分别对应于 realyee.github.io 仓库与 blog 仓库，存储对应的源文件。

首先,在搭建好原博客的情况下,进行下面步骤（以 academic_source 为例）

  1. 在 theme 的主题目录下删除 .git 目录：rm -rf theme/academia/.git

  2. 在 github 网页上 fork 所使用的主题仓库，并在网页端新建空仓库 academic_source

  3. 在 hexo 博客根目录下，创建如下目录文件 .github/workflows/autodeploy.yml (最后的文件名随意写，只要是 yaml 格式就行) 填入一下内容，并对应修改:

    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
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    name: Deployment
    on:
        push:
            branches: master

    jobs:
        hexo_depoly:
        runs-on: ubuntu-latest
        env:
            TZ: Asia/Shanghai
            GIT_NAME: realyee
            GIT_EMAIL: 615836359@qq.com
            BLOG_REPO: blog
            GH_TOKEN: ${{ secrets.GH_TOKEN }}
            THEME_NAME: maupassant

        steps:
            # checkout the source code and update the submodule recuresively,like `git submodule update --init --recursive`
            - name: Checkout source
              uses: actions/checkout@v3
              with:
                  submodules: recursive

            - name: Configure theme
              # copy the theme config and avatar to the theme folder
              run: |
                  cp ./themes/_config.yml ./themes/${THEME_NAME}/_config.yml
                  cp ./themes/source/img/avatar.png ./themes/${THEME_NAME}/source/img/avatar.png

            - name: Setup Node.js
              uses: actions/setup-node@v3
              with:
                  node-version: "18.x"

            # Install pandoc for mathjax
            - name: Install pandoc
              run: |
                  cd /tmp
                  wget -c https://github.com/jgm/pandoc/releases/download/3.1.6/pandoc-3.1.6-1-amd64.deb
                  sudo dpkg -i pandoc-3.1.6-1-amd64.deb

            - name: Install dependencies & Generate static files
              run: |
                  node -v
                  npm i -g hexo-cli
                  npm uninstall hexo-renderer-marked --save
                  npm install hexo-renderer-pandoc --save
                  npm i
                  hexo clean
                  hexo g
            - name: Git config
              run: |
                  git config --global user.name ${GIT_NAME}
                  git config --global user.email ${GIT_EMAIL}
            - name: Deploy to Github Pages
              run: |
                  git clone https://github.com/${GIT_NAME}/${BLOG_REPO}.git
                  cp -r ./public/* ./${BLOG_REPO}/
                  cd ${BLOG_REPO}
                  git add .
                  git commit -m "${{github.event.head_commit.message}}"
                  git push "https://${GH_TOKEN}@github.com/${GIT_NAME}/${BLOG_REPO}.git" master

    修改点如下：

    1. push 的 master 是指在 push 到你这个仓库 academic_source 的 master 分支时，才会触发这个 github action

    2. 对应修改 github 的用户名，邮箱，主题名以及你要发布到的仓库名，方便后面的变量引用

      1
      2
      3
      4
      5
      GIT_NAME: realyee
      GIT_EMAIL: xxxxxxx@qq.com
      ACADEMIC_REPO: realyee.github.io
      GH_TOKEN: ${{ secrets.GH_TOKEN }}
      THEME_NAME: Academia

      注意: 在 github action 中的 env 变量中不能嵌套使用变量，只能使用字面值, 像这种 REPO_NAME: ${GIT_NAME}.github.io 就会报错。 GH_TOKEN 这里需要你在 github token 这里生成一个名为 GH_TOKEN 的永不过期的 classic token，然后给予其 repo 和 workflow 的操作权限（注意生成的时候保存 token 值）。然后在 academic_source 仓库的 setting 的 secret（https://github.com/realyee/academic_source/settings/secrets/actions）（注意换为你的用户名）添加你刚刚保存的 token 值，并命名为 GH_TOKEN。

    3. cp ./themes/_config.yml ./themes/${THEME_NAME}/_config.yml：每次 update theme submodule，那配置文件就得额外自己存，然后拷贝进入。 在本地的 academic_source 的 themes 目录下保存并配置一份 theme 的 _config.yml, github action 到时就会自己复制过去。

  4. 在 hexo 博客根目录下，初始化 git 仓库，并将 fork 的仓库加入 submodule, 连接仓库，并将源文件 push 到 master 分支

    1
    2
    3
    4
    5
    6
    git init
    git submodule add https://github.com/realyee/hexo-theme-academia themes/academia
    git add .
    git commit -m "first commit"
    git remote add origin git@github.com:realyee/academic_source.git
    git push -u origin master

blog_source 的 github action 配置类似，如下：

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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
name: Deployment

on:
    push:
        branches: master

jobs:
    hexo_depoly:
        runs-on: ubuntu-latest
        env:
            TZ: Asia/Shanghai
            GIT_NAME: realyee
            GIT_EMAIL: 615836359@qq.com
            BLOG_REPO: blog
            GH_TOKEN: ${{ secrets.GH_TOKEN }}
            THEME_NAME: maupassant

        steps:
            # checkout the source code and update the submodule recuresively,like `git submodule update --init --recursive`
            - name: Checkout source
              uses: actions/checkout@v3
              with:
                  submodules: recursive

            - name: Configure theme
              # copy the theme config and avatar to the theme folder
              run: |
                  cp ./themes/_config.yml ./themes/${THEME_NAME}/_config.yml
                  cp ./themes/source/img/avatar.png ./themes/${THEME_NAME}/source/img/avatar.png

            - name: Setup Node.js
              uses: actions/setup-node@v3
              with:
                  node-version: "18.x"

            - name: Install dependencies & Generate static files
              run: |
                  node -v
                  npm i -g hexo-cli
                  npm i
                  hexo clean
                  hexo g
            - name: Git config
              run: |
                  git config --global user.name ${GIT_NAME}
                  git config --global user.email ${GIT_EMAIL}
            - name: Deploy to Github Pages
              run: |
                  git clone https://github.com/${GIT_NAME}/${BLOG_REPO}.git
                  cp -r ./public/* ./${BLOG_REPO}/
                  cd ${BLOG_REPO}
                  git add .
                  git commit -m "Github Action Automated Deployment $(date +'%Y-%m-%d %H:%M:%S')"
                  git push "https://${GH_TOKEN}@github.com/${GIT_NAME}/${BLOG_REPO}.git" master

  1. push 的 commit message 可以改为该变量 ${{ github.event.head_commit.message }}，该变量获取仓库的最新 commit message.

关于 maupassant-hexo 的小修改

  1. blog 的头像与超链接

    网站存放在子目录,如果您的网站存放在子目录中，例如 http://example.com/blog，则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/。

    由于 maupassant 在这里没有用相对路径，因此_config.yml中 avatar 的路径需要多写一层 avatar: ./blog/img/avatar.png

  2. 换掉头像的超链接： 在 blog/themes/maupassant/layout/_widget/info.pug 的 a.info-avatar(href='/', title= __(''))

  3. tagcloud 的超链接相对路径也存在问题: 在blog/themes/maupassant/layout/tagcloud.pug 改为绝对路径 a(href=config.root + 'tags/#' + tag.name, title=tag.name, rel= tag.length)

以上问题我在自己 fork 的 maupassant-hexo 仓库下也对应修改了

其他部署中遇到的小问题

  1. Github action 的 uses 和 run 不能一起使用

  2. git clone 注意指定 git http 协议，不会像浏览器似的输入 github.com 就给你补全 https

  3. ssh 在使用代理的情况下 22 端口不好用，报错如下

    1
    2
    3
    4
    5
    6
    kex_exchange_identification: Connection closed by remote host
    Connection closed by 20.205.243.166 port 22
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.

    解决办法: 在 ~/.ssh/config 中改成 443 端口

    1
    2
    HostName ssh.github.com
    Port 443

  4. 如果希望在 hexo 中 share pdf 等文件，可以在 source 下创建一个 assets 文件夹，放到里面，然后用带有博客网址的绝对路径引用文件

[Old, discard, SAVE FOR MEMORY] hexo-next 使用 netlify

本静态博客采用 hexo 模板 next 主题，markdown 源码及生成的 html 分别放在 Github 两个仓库。

通过 netlify 根据我写的简单脚本自动化部署操作 markdown 源码仓库，进行构建，并发布到 html 博客仓库。因此，我只需要对源码仓库的 markdown 进行编写，然后使用 git 同步仓库即可。

以下我的自动化构建脚本（仅供参考）:

1
2
3
4
5
6
7
8
9
10
11
#!/usr/bin/env sh
npm i
npm i -g hexo-cli
git clone --depth 1 --recursive https://github.com/violetu/hexo-theme-next themes/next
cp -r source/themes/next/* themes/next/
hexo clean
hexo g >/dev/null
hexo d
# 向 algolia 提交数据，以便搜索
export HEXO_ALGOLIA_INDEXING_KEY="a592b317037e2af5638bb820baa201e8"
hexo algolia

配置

Hexo-NexT (v7.0+) 主题配置 Hexo 添加评论系统 Disqus

新域名导致不蒜子统计数据归零

不蒜子统计数据修改

algolia 搜索不到东西

原因：部署脚本中忘记向 hexo 提交数据了。

解决方案: 那是因为你未能成功 hexo algolia 每次网站更新很多文章后,要及时提交数据, 即执行:

1
2
export HEXO_ALGOLIA_INDEXING_KEY=你为索引单独创建的key（不是search-only key）
hexo algolia

参考资料

  1. Hexo 博客指南|第十三篇:Icarus 配置 - 网站搜索插件
  2. 定制 Hexo - maupassant | Coding Pub
  3. 配置 | Hexo
  4. 利用 Github 实现(多个)个人网站 - 掘金 Github Actions 自动部署 Hexo 博客至个人服务器 - zain 的前端小窝
  5. Checkout submodules · Actions · GitHub Marketplace
  6. Github Action 自动部署 Hexo 博客 | Jckling's Blog
  7. Github’s “repository not found” error and How to fix it
  8. 让 google 收录 github pages（hexo） | 珠
  9. 使用 pandoc 正确渲染多行 MathJax 公式 - 七海の参考書
  10. GitLab 中将 Hexo 更改数学公式渲染引擎为 Pandoc - 知乎