使用Hexo搭建GitHub博客

之前使用WordPress部署个人博客，但是因为自己买主机太贵不合算，所以迁到GitHub上。开始时候使用Jekyll部署，可惜Jekyll主题普遍不够美观，所以又改用Hexo部署，这里记录一下Hexo部署的过程吧。

1. 安装

需要安装 Node.js和Git，安装 Node.js之后可以用其npm工具安装Hexo。

  1. 安装Git。 安装完成后可以通过Git Bash进入Terminal，在Terminal输入git --version查看版本信息；(也可以通过Windows的cmd命令行查看，不过我觉得Terminal更好，因为其和Linux使用体验完全一致)

  2. 安装Node.js。 安装完成后可以在Terminal输入node -v和npm -v查看版本信息；

  3. 安装Hexo。 创建Hexo的安装路径，比如D:\softwares\Hexo，在安装路径下打开Terminal进行安装：

    1
    2
    3
    npm install -g hexo-cli
    hexo init
    npm install

    此时即可在安装路径下看到生成的文件，结构附在后边。 注意：后续涉及到Hexo的命令行操作都需要在安装路径下的终端（Terminal或者cmd）执行。

2. 配置Git

首先确保自己有GitHub账户。

  1. 创建用于博客的仓库。 仓库名字必须是username.github.io，相关步骤不赘述。

  2. 本地配置Git账户并设置免密。 Terminal输入：

    1
    2
    3
    4
    5
    git config --global user.name "your username"
    git config --global user.email "your email"

    # HTTP免密，SSH免密也可以，个人比较喜欢HTTP免密，步骤更简单
    git config --global credential.helper store

    因为Hexo部署时候会自动更新仓库内容，所以必须设置免密。

  3. （Optional）可以测试一下自己上边的设置有没有问题。 

    1
    git clone https://github.com/[username]/[username].github.io.git

    如果成功拉下来就表明配置没有问题。

3. Hexo部署至GitHub Pages

3.1 部署流程

  1. （Optional）测试本地安装的Hexo是否正常。 

    1
    2
    hexo g
    hexo s

    如果一切正常，此时访问http://localhost:4000就会看到Hexo的默认页面。

  2. 安装hexo-deployer-git。 

    1
    npm install hexo-deployer-git --save

  3. 修改Hexo安装路径下的_config.yml文件末尾的deploy部分为如下形式： 

    1
    2
    3
    4
    deploy:
      type: git
      repository: https://github.com/[username]/[username].github.io.git
      branch: main

    注意两点，一是repository与上边免密方式对应，我这里是HTTP免密，如果是SSH免密，形式为git@github.com:[username]/[username].github.io.git；二是branch应该与GitHub Pages使用的分支一致，通常为main或者master。

  4. 上传部署。 

    1
    hexo d

    此时访问https://[username].github.io即可看到部署完成的网站了，同时也可以看到自己的仓库也对应更新了。

3.2 Hexo博客无法显示LaTeX公式

Hexo本身是不支持LaTeX的语法的，如果习惯与用LaTeX语法编辑公式，需要安装其他的插件。

根据查到的资料，方法主要有两种，一是使用hexo-renderer-kramed，但是这种方法我试过并不起效，可能因为已经放弃维护了；二是使用Pandoc，这个方法我试过是可用的，这里记录一下。

  1. 安装相关插件。需要先卸载掉原有的渲染器再安装： 

    1
    2
    npm uninstall hexo-renderer-marked
    npm install hexo-renderer-pandoc --save

  2. 安装Pandoc，安装完成后重启电脑生效。

  3. 配置并生效。打开主题的_config.yml加入如下键值： 

    1
    2
    3
    mathjax:
      enable: true
      per_page: true

    这里的写法是最简单的，不过我认为不是最好的，因为这里的per_page表示对每一篇文章都做渲染，如果不是每一篇文章都有LaTeX公式，那么这种做法会拖慢渲染速度。我的做法是： _config.yml加入如下键值：

    1
    2
    mathjax:
      enable: true

    在有LaTeX公式的每一篇文章的front-matter中加入mathjax: true。

  4. 清楚之前的生成数据并重新生成部署： 

    1
    2
    3
    hexo clean
    hexo g
    hexo d

3.3 修改主题

  1. 将自己想要的主题拷贝至themes文件夹下；
  2. 修改_config.yml中的theme为新主题名字；
  3. 发布和部署。

3.4 WordPress博客迁移至Hexo

Refer to：迁移 | Hexo

使用体验一般，主要存在的问题一是公式解析出问题；二是媒体文件需要重定向路径；三是表格、段落可能出错。如果WordPress里边的内容非常多，迁移工作将非常耗时。不过还能要啥自行车呢？

导出WordPress内容

WordPress需要导出的内容大致分两类，一类是文章，另一类是媒体。

  1. 文章导出。进入WordPress后台，工具->导出，导出需要的内容，将会以xml文件格式下载下来。
  2. 媒体导出。媒体文件存在于WordPress网站目录下的uploads文件夹中，将其下载到本地即可；如果是本地部署的话则位于WordPress目录下的wp-content\uploads中。

导入Hexo

  1. 文章导入。将上边下载下来的xml文件导入进来。

    1
    2
    npm install hexo-migrator-wordpress --save
    hexo migrate wordpress <wordpress.xml>

    此时即可在source\_posts下看到导入的文章了，如果有草稿则存在于source\_drafts下。

  2. 将媒体文件放在合适的地方。比如我倾向于放在source\assets下。

  3. 逐篇校对导入的文章，将媒体重定向为新的路径，同时注意公式等有没有解析出错。

  4. 部署上传。

4. 更多Hexo相关

4.1 Hexo安装路径下的文件信息

这里仅列出部分比较重要的文件夹/文件：

1
2
3
4
5
6
7
Hexo_dir
├── public			# 将被更新到博客仓库的内容
├── scaffolds		# 模版文件
├── source			# 存放markdown格式的博客
├── themes			# 存放Hexo主题
├── _config.yml		# 网站的配置信息
└── package.json	# 应用程序的信息

4.2 常用Hexo命令

Refer to：Documentation | Hexo

新建文章

1
2
hexo new [layout] <title>
hexo n [layout] <title>

layout选项如下：

Layout 保存路径 说明
post source/_posts 默认位置，该路径下的文章会被生成和发布
draft source/_drafts 作为草稿，不会被生成和发布
page source

使用实例：

1
2
3
4
5
6
# 在source\_posts下生成post-name.md，打开并编辑即可
hexo new "post-name"

hexo new draft "test"	# 在source\_draft下新建草稿test.md
hexo publish "test"		# 推送到source\_posts下
hexo --draft 			# 查看已有的草稿

文章生成和发布

1
2
3
4
5
6
# 生成博客页面
hexo g
# 启动本地预览
hexo s
# 部署和发布至GitHub Pages
hexo d