Hexo+Github搭建个人博客

发表于 | 更新于 | 分类于 | 评论数：

网上关于如何用Hexo + Github Pages来搭建静态博客的文章已经有很多了，本文在这里主要只是想单纯地把自己创建博客、修改部分设置的过程记录下来，一来作为自己的备份，二来也供感兴趣的人查阅尝试。

开发环境准备

开发环境主要包括两个部分：git和npm。前者用于将博客内容push到Github上托管以便更新博客内容，后者则是包括Hexo在内的众多Node.js开发工具的管理包，可以类比于Python使用者常用的的anaconda。

npm

安装Node.js和npm，如果读者已经在以前安装过，则可以略过此步，如果读者不确定，也可以直接检查npm的版本号，只有安装了Node.js和npm，才能正确显示npm版本号。

安装node.js和npm

1
2
$ sudo apt-get install nodejs 
$ sudo apt-get install npm

检查npm版本号

1
npm -v

将npm的下载源更换为taobao，以提高下载速率

1
2
$ sudo npm install nrm -g --registry https://registry.npm.taobao.org
$ nrm use taobao

使用npm下载Hexo

1
$ sudo npm install hexo-cli -g

git

由于最终博客是要托管到Github上的，所以git是必要工具。

安装git，并设置全局的user和email参数，以方便以后的更新，如果读者以前已经设置过，那么这步可以跳过。

1
2
3
$ sudo apt-get install git
$ git config --global user.name "your github account name" 
$ git config --global user.email "your github account email"

Hexo的代码更新需要给Github提供ssh秘钥，因此有必要在开始设置博客之前给Github设置秘钥。
检查电脑是否已经有相关秘钥（如果是初次安装git，那么可以跳过这步检查，直接设置秘钥）

1
$ ssh -T -v git@github.com

如果检测结果显示permission denied，那么就需要设置秘钥

1
$ ssh-keygen -t rsa -C "your github account email"

过程中会多次出现问询，一路回车即可，最后秘钥保存路径是/home/youraccount/.ssh/，查看并复制公钥内容，并提供给Github。

1
$ cat /home/youraccount/.ssh/id_rsa.pub

进入github网站，在setting页面找到SSH相关选项并打开，创建新秘钥并将公钥内容复制进Key值。

搭建博客

创建Github的托管仓库

创建新的repo，repo名称应该是username.github.io。

在本地初步建立hexo

初始化Hexo博客项目，首先进入想要存放代码的附文件夹

1
2
3
$ hexo init <blog>
$ cd <blog>
$ npm install

测试是否成功

1
2
$ hexo generate
$ hexo server

修改配置文件

Hexo中，配置文件的名字是__config.yml，但是在博客住文件夹的主页和各个主题内部的配置文件，名称一模一样，读者需要时刻注意。以后会用‘配置文件’和‘主题配置文件’来分别称呼这两个__config.yml文件以示区别。

修改配置文件中的网站、标题、作者等等信息以及URL。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Site
title: 荒草园子 
subtitle: 这里没有酒也没有故事
description:
author: JoshuaW1990
language: zh-Hans
timezone:

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: https://joshuaw1990.github.io 
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:

修改配置文件中的deploy信息（这一步很关键，直接决定能否正确将代码托管到github上面并建立博客），repo项应该填写之前在Github上创建的用于托管博客的repo地址。

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repo: git@github.com:JoshuaW1990/joshuaw1990.github.io.git
  branch: master

测试

至此，Hexo的基本功能已经实现了，可以按照以下命令创建一篇post并在本地进行查看：

1
2
3
4
5
6
# 创建一篇名叫test的文章
$ hexo new test
# 页面渲染
$ hexo generate
# 在本地打开页面测试
$ hexo server

如果本地测试没有问题，那么也可以将其部署到github上面去

1
$ hexo deploy

至此，一个静态博客的功能就算基本实现了。

博客功能的增加

主题替换

Hexo的默认主题我个人并不喜欢，因此，选择了Next主题作为替换。按照文档的要求，下载稳定版本的主题，并放置到/themes/文件夹中。主题配置文件暂时没有需要修改的，但是配置文件中关于主题的那一栏需要进行替换。

1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: next

增加菜单页面

现阶段，菜单页面还显得过于简单，并不能满足需要，因此我决定增加一系列菜单：

  • 标签
  • 分类
  • 关于
  • 笔记

增加菜单页面的步骤基本相同，主要分为三步。
第一步：在Hexo中创建菜单页面（以标签页为例）

1
$ hexo new page tags

第二部：修改主题配置文件中的菜单内容，主要就是去掉不需要的注释符号，另外给没有提供在主题配置文件中的菜单内容也添加进来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# When running the site in a subdirectory (e.g. domain.tld/blog), remove the leading slash from link value (/archives -> archives).
# Usage: `Key: /link/ || icon`
# Key is the name of menu item. If translate for this menu will find in languages - this translate will be loaded; if not - Key name will be used. Key is case-senstive.
# Value before `||` delimeter is the target link.
# Value after `||` delimeter is the name of FontAwesome icon. If icon (with or without delimeter) is not specified, question icon will be loaded.
menu:
  home: / || home
  about: /about/ || user
  tags: /tags/ || tags
  categories: /categories/ || th
  archives: /archives/ || archive
  #schedule: /schedule/ || calendar
  #sitemap: /sitemap.xml || sitemap
  #commonweal: /404/ || heartbeat
  笔记: /note/

最后，再根据需要修改每一个菜单页面，推荐开头部分关闭评论功能如下：

1
2
3
4
5
6
---
title: 标签
date: 2017-11-26 21:07:31
type: "tags"
comments: false
---

其他插件的使用

评论功能

评论功能本来计划使用多说，但是多说已经关闭，经过考虑，暂定使用gitalk，目前测试显示能够正常使用。其使用流程完全参照自Next主题的Gitalk移植，因此这里不做赘述。

因为换电脑之后重新搭建了博客，所以在更新Next主题的时候发现已经可以内置gitment的功能，因此决定换成使用gitment来实现评论功能。具体方法非常简单，直接根据参考文章（见底部）即可。

评论设置的问题

使用gitment或者gittalk进行初始化的时候可能会出现Error: Validation Failed的问题，原因在于汉字标题导致编码后label超过50，解决方法有几种：

  1. 将_config.yml的permalink中的title替换为id
  2. 修改themes/next/layout/_comments/gitment.swig中的id：
1
2
3
4
5
6
7
8
9
var gitment = new Gitment({
      id: window.location.pathname,
      owner: 'github id',
      repo: 'github  issue repo',
      oauth: {
        client_id: 'XXX',
        client_secret: 'XXXX',
      },
    })

有人将id那一行改为id: '<%= post.date %>',，也有人将其改为id: decodeURI(window.location.pathname)。经过比较，个人更喜欢后者。

数学公式

mathjax

因为偶尔可能需要在日志里面写一些公式，而自己又不太喜欢用截图来展示公式的方法，所以当时的考虑是使用mathjax或者pandoc。幸运的是，Next主题已经集成了mathjax，按照Next文档修改主题配置文件下段内容

1
2
3
4
5
# MathJax Support
mathjax:
  enable: true
  per_page: true
  cdn: //cdn.bootcss.com/mathjax/2.7.1/latest.js?config=TeX-AMS-MML_HTMLorMML

之后在需要使用mathjax的文章开头打开mathjax开关，如下：

1
2
3
4
5
6
7
8
title: 统计学习方法概论
date: 2017-11-27 17:59:59
tags:
- 统计学习方法
- 机器学习
categories:
- 读书笔记
mathjax: true

到这里为止，mathjax已经可以正常工作了，公式也能按照latex格式书写了，但是依然会出现一些bug。具体原因在于默认的Hexo渲染引擎”hexo-renderer-marked”在渲染markdown和mathjax渲染引擎在渲染latex公式时会发生冲突，因此需要更换渲染引擎，或者手动定义Hexo渲染引擎内的部分rule文件来避免冲突，此处为了简单起见，更换了Hexo的渲染引擎

更换渲染引擎

进入博客路径，按如下命令卸载原来的渲染引擎marked并安装新的渲染引擎kramed。

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

更换渲染引擎后，行间公式就已经可以正确显示了，但是行内公式依然在渲染时会存在冲突，因此还要继续修改某些规则。

找到kramed引擎中关于渲染规则的定义文件（即node_modules\kramed\lib\rules\inline.js），推荐先保存一份再进行修改。
找到inline.js中的escape变量，并进行修改

1
2
//  escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/,
    escape: /^\\([`*\[\]()#$+\-.!_>])/

找到inline.js中的em变量，并进行修改

1
2
//  em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,
    em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/

对博客文件重新渲染

1
2
$ hexo clean
$ hexo generate

这样就算完成了。

todolist

如果以后还有什么想要改进的地方也会先记录在这里，然后尝试修改。

参考文献：
使用 Github Pages 和 Hexo 搭建独立博客
Permission denied (publickey). fatal: Could not read from remote respository.解决办法
Next主题的Gitalk移植
Next
在Hexo中渲染MathJax数学公式
Hexo-Next 添加 Gitment 评论系统