在 github.io 上用 Hexo 搭建博客

03 Feb, 2017

Preface

之前的博客是在 OpenShift 上搭建的 Typecho。但 Typecho 已经有4年没更新了，社区也很不活跃，备份博客数据也很麻烦。所以我干脆直接把博客搬到 GitHub Pages 上，因此也带来了一些便利：

备份博客只需要把 Markdown 文件连同对应的文件夹打包即可
自带的域名也更有逼格了：https://oing9179.github.io
Hexo 社区活跃，出了问题基本都有现成的解决方法
github.io 屏蔽猫抓搜索引擎的爬虫，借此来提高访客的门槛

下面开始介绍博客的迁移过程。

安装 / 配置 Hexo

我看好多人都直接用 <username>.github.io 作为博客地址，我把这个地址预留了下来留给以后加个首页什么的，然后把博客放在 /blog/ 目录下，根目录下放个 html 把浏览器重定向到 /blog/ 下就行了。

安装 Hexo

参考下面的命令

sudo apt-get install nodejs nodejs-legacy
npm install -g hexo-cli

有以下几点注意事项：

npm install 的时候提示输入密码的话就输入。
因为众所周知的原因，npm 的下载速度很慢，可以为其设置 HTTP 代理：
```
npm config set proxy http://127.0.0.1:8080
npm config set https-proxy http://127.0.0.1:8080
```
或者使用 taobao 的 npm 镜像，请移步 Taobao npm Mirror.

配置 Hexo

参考如下命令

# 创建一个静态网站名为 blog
hexo init blog
cd ./blog/
# 安装 RSS 和 SiteMap 插件，RSS 为了方便读者 SiteMap 为了方便搜索引擎爬虫。
npm install hexo-generator-feed hexo-generator-sitemap --save

编辑 _config.yml，在文件末尾加入下面的代码：

# SiteMap configuration
# https://github.com/hexojs/hexo-generator-sitemap
sitemap:
  # 想配置 sitemap.xml 的模板，请移步到 ./node_modules/hexo-generator-sitemap/sitemap.xml
  path: sitemap.xml

# RSS configuration
# https://github.com/hexojs/hexo-generator-feed
feed:
  type: rss2
  path: rss2.xml
  # RSS里最多包含几篇文章
  limit: 6
  hub:
  # 是否把文章全部内容也包含进去
  content: false

然后参照 Hexo configuration 来配置 _config.yml。需要注意的是：因为我要把博客放在 /blog/ 目录下，所以要修改 _config.yml：

# 找到 root 项并修改为 /blog/
root: /blog/

最后在 blog 目录下执行 hexo server --debug，然后打开浏览器访问终端里显示的 URL 来预览网站。

安装 / 配置 Hexo theme: NexT

建议不要在 hexo server 运行的时候安装主题。因为文件的改动会导致 Hexo server 重新生成网站，如果有些文件还没下载完或者文件内的语法有问题，就会导致 Hexo server 报错，之后再刷新网页的话就什么也打不开。

参考下面的命令

cd ./themes/
git clone https://github.com/iissnan/hexo-theme-next.git
# 回到 blog 目录下
cd ../

编辑 _config.yml：

# 找到 theme 并将其设定为 next
theme: next

然后就可以按照官方文档对 NexT 主题进行配置了。

添加 Categories / Tags / Links / About 页面

创建这些页面的方法是一样的，需要改动的只有 Markdown 文件头部的 yaml 配置项。

# 回到 blog 目录，然后执行如下命令
# 下面的 "About" 可以换成 "categories" 或者其他的都可以，大小写敏感.
hexo new page "about"

然后编辑 ./source/about/index.md，参考下面内容对 Markdown 头部的 yaml 配置项添加如下内容：

名称	值	注释
type	可选值: tags, categories.	设置页面类型. 除 categories 和 tags 外的页面不需要设置 type 字段
comments	可选值：true, false.	设置是否开启页面底部的评论功能

例如创建了一个 Categories 页面并关闭页面的评论功能，那它的 yaml 配置项大概就是这样：

title: Tags
date: 1900-01-01 00:00:00
type: "categories"
comments: false

页面创建完成后，如果在预览网站的时候出现错误什么的，尝试执行下面的命令来清空缓存：

# 在 blog 目录下执行命令
hexo clean
rm ./db.json

创建 Links 页面的后需要对主题进行一些简单的配置才能在博客的导航栏上显示出来：

切换到主题所在目录：./themes/next/

编辑 _config.yml

# 导航栏里项目的显示顺序就是下面 menu 项里从上往下的顺序.
# 找到 menu 项然后直接在下面添加一行即可，像这样：
menu: 
  tags: /tags
  # 添加 links 项，格式 "<变量名>: <网页路径>"，这个 变量名 稍后还会用到.
  links: /links
  about: /about

# 然后找 menu_icons 项，为 links 添加一个图标，想要什么图标可以在 http://fontawesome.io/icons/ 找.
menu_icons:
  # 格式：<变量名>: <不含 "fa-" 前缀的CSS类名>
  links: link

编辑 ./languages/<语言>.yml，我给博客设置的语言是英文所以我应该编辑 en.yml

# 找到 menu 项目
menu:
  # 直接在最后添加一行即可，格式：<变量名>: <要显示出来的文字>
  links: Links

运行 hexo clean 清空 Hexo 缓存，然后运行 hexo server --debug ，然后打开网页浏览器查看效果

配置 Disqus

首先到 Disqus 注册一个帐号，然后按照向导（非常简单）创建一个 Site，把 Site 的 Shortname 找出来备用。 NexT 主题下只需要非常简单的配置就可以启用 Disqus。

# 切换到主题文件所在目录
cd ./themes/next/
# 编辑 _config.yml
vim ./_config.yml

查找字段 disqus_shortname，然后改成自己的 shortname 即可。

迁移旧博客到 Hexo

这一步骤可谓是最无聊的步骤了。使用命令 hexo new "<文章标题>" 来创建 Post（Post 在这里译为文章），然后把原来博客的内容复制进去，然后再对新的 Post 的 Markdown 文件头做些编辑，例如下面这样：

---
title: 文章标题
# 文章的创建时间
date: 2016-11-26 17:25:00
# 文章的最后修改时间
updated: 2017-01-17 00:00:00
categories:
    - Post 的分类
    - "Post 的分类" 的子分类
    - "Post 的分类 的子分类" 的好多个子分类
tags:
    - 第一个 tag
    - 第二个 tag
    - 还可以有好多个 tag
# 仅对本篇文章禁用评论功能
comments: false
---

<文章正文>

BLumia 用 PHP 写了段脚本在 BLumia / Typecho2Hexo-Helper，可以把 Typecho 的博客内容导出来，

GitHub Pages

因为我想把博客放在 /blog/ 目录下而不是网站的根目录下，为此我需要创建两个 Repository：一个 blog 仓库用来放博客本体，一个 <用户名>.github.io 仓库用来把浏览器从 / 重定向到 /blog/。

创建 / 配置 `blog` 仓库

切换到 blog 目录下
使用 hexo 生成静态站点
```
hexo generate
```
在生成好的站点目录下创建 git 仓库
```
cd ./public/
git init
```
因为我搭建博客用的是 Hexo 而不是 Jekyll，创建文件 .nojekyll 来关闭 GitHub Pages 的 Jekyll 相关功能
```
touch ".nojekyll"
```
为仓库创建新的分支名为 gh-pages
```
git checkout -b "gh-pages"
```
分支创建完成后 git 会自动将 gh-pages 设置为当前分支

添加所有文件到 git 工作空间并 commit

git add --all
git commit -m "Created blog with theme settle up."

在 GitHub 上创建一个新的 Repository，repository 名称随意，本文以 blog 作为 repository 名称
为本地仓库添加远程仓库，并 push 到远程仓库
```
git remote add origin https://github.com/<用户名>/blog.git
git push
```
提示输入用户名和密码的话，就输入。
用网页浏览器访问 https://<用户名>.github.io/blog/ 来查看效果

创建 / 配置 `oing9179.github.io` 仓库

切换到任意不是 blog 的目录下
创建 <用户名>.github.io，这里以 oing9179.github.io 为例
```
git init "oing9179.github.io"
cd ./oing9179.github.io/
```

创建两个文件，一个是 index.html 文件内容如下，另一个是 .nojekyll 来禁用 GitHub Pages 的 Jekyll 功能

<!DOCTYPE html>
<html>
<head>
    <title>Redirecting...</title>
    <!-- 下面这行告诉浏览器 将页面重定向到 /blog/ 目录下 -->
    <meta http-equiv="refresh" content="0;URL='/blog/'" />
</head>
<body>
Redirecting you to <a href="/blog/">/blog/</a>...
</body>
</html>

然后执行命令来提交更改到本地仓库

git add --all
git commit -m "Initial commit."

在 GitHub 创建一个名为 oing9179.github.io 的仓库，然后给本地仓库添加远程仓库，然后 push
```
git remote add origin https://github.com/oing9179/oing9179.github.io.git
git push
```
用网页浏览器访问 https://oing9179.github.io，浏览器应该会自动重定向到 /blog/ 页面

修复博客放在子目录时 hexo 生成错误的永久链接

我将博客部署到 github.io 上后，把 sitemap.xml 提交到了 Google Search Console。然而 Google 告诉我我的 sitemap.xml 里部分链接 404，于是发现了下面这个 bug：

受影响版本：v3.2.2 (GitHub issue #1812) 当网站被放在子目录下的时候（并对 _config.yml 的 url 和 root 做了正确的设置），使用 hexo generate 生成出的网站的永久链接（Permalink）会变成这样（假设 root 设置成 blog）：http://yoursite.com/blog/blog/。

不过还好，这个 bug 已经在 Commit 5234c4a85d 修复了。按照如下步骤操作以修复本地 hexo：

切换到 blog 目录下的 ./node_modules/hexo/
把 lib 目录改名为 lib.bak
从这里把修好 bug 的 hexo 下载回来并解压
将解压出来的目录下的 lib 目录复制到 blog 目录下的 ./node_modules/hexo/
执行命令 hexo clean && hexo generate 来重新生成静态网站警告：重新生成静态网站会导致 ./public/.git 文件夹被删除，在生成静态网站之前需要先把它移走。

更新历史

03 Feb 2017: 首次发布 04 Feb 2017:

添加：修复博客放在子目录时 hexo 生成错误的永久链接

12 Feb 2017:

删除：“可以安装并使用 cnpm”。原因是 jxpxxzj 提到：

cnpm 的那种安装方式会导致 electron-packager 几乎无法工作，因此强烈不推荐 cnpm。建议先安装 nrm (Npm Registry Manager) 然后再 nrm use taobao。
修改：删除 sitemap_template.xml 及其相关内容，并改用 ./node_modules/hexo-generator-sitemap/sitemap.xml 来修改 sitemap 的模板
添加：清空 Hexo 缓存的命令行
小修小改

References

#github.io #hexo