今天发现新浪博客几乎已经是强弩之末了，加之学校不少人有创建类似的博客，于是心血来潮自己搭一个。

主要基于“简书”上的有关教程和另一个博客网站所有者的教程操作。

GitHub

首先生成了一个名为k-pk66.github.io的库。这个库的名称是GitHub账号的用户名。生成之后将主Branch更名为master，并通过Settings>Pages>Build and Deployment将Branch设定为了master。

终端（Terminal）

通过homebrew为macOS安装git和nvm。后者是Nodejs版本管理器，可以轻松切换Nodejs版本。

1
2
3
4
5
brew install git
brew install nvm
mkdir ~/.nvm
export NVM_DIR=~/.nvm
(brew --prefix nvm)/nvm.sh

之后运用nvm安装Node.js。

1
nvm install 4

随后通过npm安装hexo。

1
sudo npm install hexo-cli -g

在此之后，创建名为k-pk66.github.io的文件夹并通过命令行打开。

1
2
hexo init k-pk66.github.io
cd k-pk66.github.io

文件夹中有名为_config.yml的配置文件；将该文件中的各键值对按官方提供的指引文档进行修改即可。由于设定的博客位于GitHub，因此需要对文件中的“部署（deploy）”区域进行如下设置。

1
2
3
4
deploy:
  type: git
  repo: http://github.com/k-pk66/k-pk66.github.io.git
  branch: master

文件夹所属sources文件夹的_post中有参考性质的Markdown文件。通过下方指令

1
hexo new "makeRecord"

创建新的博客。

（更多撰写指引，请看这里）

之后通过指令

1
hexo s

对博客网页在本地进行测试。

随后通过指令

1
npm install hexo-deployer-git --save

安装自动部署发布工具。此后，每次更新博客只要输入指令

1
hexo clean && hexo g && hexo d

即可完成上传。

GitHub的身份验证

在首次输入上一章节的最后一个指令时命令行会引导输入GitHub账密。用户名与GitHub一致即可；当输入密码与正常登录所使用的密码一致时命令行将报错。
报错信息为“GitHub自2021年8月13日起不再支持密码认证”；因此需要通过GitHub账户个人设置中的开发者设置生成权限密钥（Personal access tokens）。在生成之后将输入密码替代为此token，即可完成上传。

主题

在本博客发布为止博客使用的是butterfly主题。

在文件夹k-pk66.github.io的终端输入

1
git clone -b master https://gitee.com/immyw/hexo-theme-butterfly.git themes/butterfly-former

安装完成后themes文件夹即新增了butterfly主题的一部分文件。随后输入

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

安装渲染器等插件。最后在_config.yml文件中修改theme键值为butterfly，再进行测试即可查看效果。

其他功能

新增其他语言

本章节将会对在butterfly主题中新增其他非中文语言的版本页面进行引导。

本章节参考：Shannon Hung有关内容的博客

使用_config.yml复制出config-zh.yml与config-en.yml两文件，随后删除原本的_config.yml。之后分别对两语言的.yml文件指定区域修改如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# config-en.yml

# 設定成英文
language: en 

# 添加 en 
url: https://<url-url>/en
root: /en/

# 指定啟動的路徑
source_dir: source-en
public_dir: public-en

# 把中文的 source 進行排除
include:
exclude:
ignore:
  - source/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# config-zh.yml

# 設定成中文 
language: zh-TW

# 使用原本的url
url: https://shannonhung.github.io
root: /

# 指定啟動的路徑
source_dir: source
public_dir: public

# 把英文的 source 進行排除
include:
exclude:
ignore:
  - source-en/

之后在原本中文文件夹source中新建文件夹self，随后创写文件btf.js。

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
(() => {
  // 判斷是否為英文
  const isIncludeEN = item => {
    const key = '/en/'
    return item.includes(key)
  }

  // 建立 重新導向到不同語言的 url 
  window.loadFullPage = (url) => {
    window.location.href = url
  }

  // 重新導向 
  const eventFn = (elements, includeEN) => {
    elements.forEach(item => {
      if (!includeEN || !isIncludeEN(item.href)) {
        item.href = `javascript:loadFullPage('${item.href}');`
      }
    })
  }

  // 判斷目前是否為英文
  const nowIncludeEN = isIncludeEN(window.location.href)
    
  const selector = nowIncludeEN
    ? document.querySelectorAll('a[href^="https://k-pk66.github.io"]')
    : document.querySelectorAll('a[href^="/en/"]')

  eventFn(selector, nowIncludeEN)
})()

随后复制source，粘贴在根目录下并将其命名为source-en作为存储英文页面的文件夹。此时btf.js应当也在source-en/self中。

之后将_config.butterfly.yml分身为config-butterfly-en.yml和config-butterfly-zh.yml。在这两个文件的底部分别添加btf.js。

1
2
3
4
# config-butterfly-former-zh.yml
inject:
  bottom:
    - <script data-pjax src="/self/btf.js"></script>
1
2
3
4
# config-butterfly-former-en.yml
inject:
  bottom:
    - <script data-pjax src="/en/self/btf.js"></script>

相信此时读者已经看出来了——所有在英文页面配置文件中的文件路径都需要在原本的路径的前方新增/en/。这是因为，本质上这两个页面互不相通；添加/en/才能使文档正常调用。

之后在package.json中调整"scripts"中的指令表，使命令行可以产生public-en文件夹——如此才能将英文页面推入仓库并予部署。

1
2
3
4
5
6
7
"scripts": {
  "push": "hexo clean && hexo g && hexo douban && gulp && hexo deploy",
  "show": "hexo clean && hexo g && hexo s",
  "update": "git init && git add . && git commit -m 'backup' && git push origin main",
  "kk": "hexo clean && hexo g && hexo deploy",
  "en": "hexo clean && hexo g --config config-en.yml && hexo s --config config-en.yml"
}

最后新建deploy.sh文件对命令行的指令功能进行调整。本质上，这一文件会将两个不同语言的config、config-butterfly文件分别视作两个_config.yml和_config.butterfly.yml并分别进行部署或显示。

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
#!/bin/bash

while [[ "$#" -gt 0 ]]; do
    case $1 in
        -h|--help) 
            echo "Usage: bash.sh [en|zh|all|show <en|zh>|-h]"
            echo "Options:"
            echo "  [deploy|d] en   Deploy English configuration to GitHub Pages"
            echo "  [deploy|d] zh   Deploy Chinese configuration to GitHub Pages"
            echo "  [deploy|d] all  Deploy both English and Chinese configurations to GitHub Pages"
            echo "  [show|s] en     Execute npm run show for English configuration"
            echo "  [show|s] zh     Execute npm run show for Chinese configuration"
            echo "  -h, --help      Display this help message"
            exit 0
            ;;
        d | deploy)
            lang=$2
            if [ "$lang" = "en" ] || [ "$lang" = "zh" ]; then
                cp "config-$lang.yml" _config.yml
                cp "config-butterfly-$lang.yml" "_config.butterfly.yml"
                npm run kk
                echo "Deploy $1 success!"
            elif [ "$lang" = "all" ]; then
                for lang_choice in "zh" "en"; do
                    cp "config-$lang_choice.yml" _config.yml
                    cp "config-butterfly-$lang_choice.yml" "_config.butterfly.yml"
                    npm run kk
                    echo "Deploy $lang_choice success!"
                done
            else
                echo "Error! Please input 'en' or 'zh' or 'all'!"
            fi
            ;;
        s | show)
            lang=$2
            if [ "$lang" = "en" ] || [ "$lang" = "zh" ]; then
                cp "config-$lang.yml" _config.yml
                cp "config-butterfly-$lang.yml" "_config.butterfly.yml"
                npm run show
                echo "Running npm show!"
            else
                echo "Error! Please use './bash.sh show en' or './bash.sh show zh'!"
            fi
            shift # Move to the next argument after 'show'
            ;;
        *)
            echo "Error! Please input deploy <en|zh|all> or 'show <en|zh>' or '-h' for help!"
            exit 1
            ;;
    esac
    shift
done

之后将该文件通过命令行设为可执行文件。

1
chmod +x deploy.sh

此后，只要输入指令

1
./deploy.sh d all

即可将所有语言均予部署。

TikZ支持

通过指令

1
npm install hexo-filter-tikzjax

实现对TiKz包的安装。这个包将支持把TikZ代码渲染为SVG矢量图；只需要在每篇文章的Front matters区域输入tikzjax: true即可。

详细操作可以通过这里寻得。

Troubleshoot

后续在实际撰稿过程中遇到了一些问题，在这里列举。

过大文件

由于GitHub本身对上传的单个文件空间大小有要求（不得超过100MB），因此不建议上传视频。

如误上传了超过100MB的文件，命令行会在push时返回信息

1
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.

在稿件中对应位置移除该大文件后push，依然会有此报错。解决此问题，需要在.deploy_git文件夹中打开命令行，输入指令

1
git log

通过回车寻找上传大文件前的最后一个版本（可以根据时间找；也可以是更早的版本），复制这一版本对应commit后方的版本号。

假定命令行有输出

1
2
3
4
5
6
7
8
9
10
11
commit 6657f1c73af4254557e77c3dd2c681ddf10e5d51 (HEAD -> master)
Author: K-PK66 <example@example.com>
Date:   Mon Jun 3 12:26:51 2024 +0800

    Site updated: 2024-06-03 12:26:49

commit 35a21f2e94c5022503cfbce29ff2dacf2b497cd2
Author: K-PK66 <example@example.com>
Date:   Mon Jun 3 01:28:30 2024 +0800

    Site updated: 2024-06-03 01:28:30

想要恢复至2024年6月3日东八区时间1时28分30秒的版本，则需要用指令

1
git reset 35a21f2e94c5022503cfbce29ff2dacf2b497cd2

将.deploy_git恢复至当时。然后再进行推送即可恢复正常。

字体

通过在主题文件夹中的source文件夹中新建fonts文件夹，并向其中放入字体ttf（或otf，woff等）扩展名的字体文件。随后在主题文件夹中css文件夹新建css文件并向其中引入该字体。

以向本博客引入字体“A-OTF Shin Go Pro Regular”，并将其命名为“A-OTF Shin Go Pro R”为例。将名为AOTFShinGoProRegular.woff的字体文件放入fonts文件夹，随后在css文件夹中新建my.css并编写如下：

1
2
3
4
5
6
7
8
9
10
11
12
@font-face {
    font-family: 'A-OTF Shin Go Pro R';
    font-style: normal;
    font-weight: normal;
    src: local('A-OTF Shin Go Pro R'), url('../fonts/AOTFShinGoProRegular.woff') format('woff');
}


body{
    font-family: 'A-OTF Shin Go Pro R', sans-serif;
    font-weight: 400;
}

之后在主题_config.yml文件中指定板块写如下代码

1
2
3
4
5
6
7
8
# Inject
# Insert the code to head (before '</head>' tag) and the bottom (before '</body>' tag)
# 插入代码到头部 </head> 之前 和 底部 </body> 之前
inject:
  head:
    - <link rel="stylesheet" href="/css/my.css">
  bottom:
  # - <script src="xxxx"></script>

即可。

特别地，如果仅想对特定的字母/符号使用该字体，可使用在线字体提取工具（例如这个工具）对指定字符的该字体进行提取并重新包装为新字体文件，按上述方法安装。

上传过程中遭遇卡顿（仅限中国大陆地区）

由于GitHub在中国大陆地区的访问过程中已经收到严重的DNS污染，不可避免地会出现在使用上传博客指令后无法连接GitHub服务器（或上传过程中断开连接）的情况。针对此可灵活使用中国大陆访问较快的Gitee进行操作。

由于Gitee Pages在2022年左右起已经停止服务，所以此处不推荐直接在Gitee上建立仓库的手段。

首先建立一个Gitee账号并创建仓库。之后在该仓库“管理/仓库镜像管理”中设置GitHub的仓库作为Gitee仓库的镜像，并设置方向为由Gitee仓库Push到GitHub仓库。随后在GitHub个人设置中使用先前“GitHub的身份验证”章节提到的方法生成权限密钥之后在指定位置输入；在完成添加镜像后，将_config.yml指定位置修改如下：

1
2
3
4
5
6
7
deploy:
  #- type: git
  #  repo: https://github.com/k-pk66/k-pk66.github.io.git
  #  branch: master
  - type: git
    repo: git@gitee.com:k-pk66/blog.git
    branch: master

再输入博客上传指令，命令行将会在Gitee的仓库中更新博客；而仓库更新后会自动将更改写入GitHub。这时可以明显感觉到上传的速度增快了。