[笔记]使用Hexo搭建Github博客

平台: Windows 10
使用的 Hexo 主题: Next

平台安装

1. 安装 Git (Git 官网) 并如下配置:
   打开Git Bash:

   # 针对你的 Github 账户生成一个 SSH key:
   ssh-keygen -t rsa -b 4096 -C "username@host.com"
   # 按三次回车, 密码设为空
   # 最终在 C:\Users\Username 下生成 .ssh 文件夹并产生 id_rsa, id_rsa.pub 文件
   
   # 验证 SSH 代理运行:
   eval $(ssh-agent -s)
   # 若正常运行则输出 Agent pid xxxxx
   
   # 添加 SSH 私钥至代理:
   ssh-add ~/.ssh/id_rsa
   
   # 复制 SSH 公钥到 Github 账号:
   clip < ~/.ssh/id_rsa.pub
   # 然后网页转到 https://github.com/settings/keys (在登陆的前提下)
   # 点击 New SSH key, title 随意, 在 key 文本框 Ctrl+V
   
   # 验证 SSH 连接
   ssh -T git@github.com 
   # 显示: Hi Username! You've successfully authenticated, but GitHub does not provide shell access.
   

2. 安装 Node.js (Node.js 官网, 安装完即可使用 npm )).

3. 在 Github 上创建 username.github.io 仓库.

4. 安装并配置 Hexo:
   安装:

   npm install -g hexo-cli
   

   (该指令表明 Hexo 为全局安装).

   确定一个空文件夹(必须是空的)作为 Hexo 站点, 在文件夹内右键菜单,选择 “Git Bash Here” 打开 Git Bash, 输入:

   hexo init
   

   在该文件夹下产生一些 Hexo 文件. 然后打开刚生成的站点配置文件 _config.yml, 必要的修改如下:

   title: XXX's Blog
   author: XXX
   language: zh-CH           # 或 language: en 等等
   
   theme: next
   
   deploy:
   type: git
   repo: git@github.com:XXX/XXX.github.io.git
   branch: master
   

5. Next 主题安装与配置
   安装并配置 Next 主题 (Next 官网, 配置教程官网有).
   (Hexo 与 Next 主题各有一个 _config.yml 配置文件, 注意区分.)

网站发布至 github.io

在 Hexo 目录安装:

npm install hexo-deployer-git

首先我们可以在本地调试而不急于上传 Github:
(同样在 Hexo 目录)

hexo clean
hexo g
hexo s

执行完毕后打开 http://localhost:4000 即可查看主页. 针对 Markdown, 主题文件的任何修改, 保存后对网页按 F5 刷新立即可查看修改结果. 针对 Hexo 的修改似乎需要重启服务器.

要发布至 Github 则:

hexo clean
hexo g
hexo d

指令执行完毕即可前往 github.io 查看结果.

踩坑

生成页面

生成新文章页

hexo n <post_name>

本质上就是在 source/_posts/ 下生成一个 <post_name>.md 和一个 <post_name> 的文件夹. 其中 md 文件根据模板生成.

添加 标签 (Tags) 和分类 (Categories) 页面

默认是没有这些页面的, 当在主页点击标签, 分类页面时会显示 Cannot GET /tags/ 或 Cannot GET /categories/.

添加方法:

hexo new page tags

然后进入 source/tags/, 修改 index.html:

---
title: tags
date: 2019-04-11 16:35:04
type: "tags"
comments: false
---

categories, about 等同理.

文章的标题, 发布时间, 与标签等设置与模板

在 Markdown 文件最开头插入如下内容:

---
title: 标题标题标题标题
categories:
  - 分类
  - 子分类
  - 子子分类
tags:
  - 标签1
  - 标签2
  - 标签3
abbrlink: 41653
date: 2017-10-22 15:12:50
---

其中 title 必须填写, 不会根据文件名自动生成; abbrlink 是自动生成的, 请勿自己输入; 其余三项可有可无.

Hexo 提供 Markdown 生成模板(仅限使用 hexo n <file_name> 时), 打开 Hexo 站点目录下的 scaffolds/post.md, 若想要生成上述内容可如下填写:

---
title: {{ title }}
date: {{ date }}
categories:
  - 
tags:
  - 
---

Markdown 与图片的问题

1. 在 Hexo 站点文件夹下打开 Git Bash, 输入:

   npm install hexo-asset-image --save 
   

2. 打开站点配置文件 _config.yml, 修改:

   post_asset_folder: true
   

   以后再使用 hexo n <post_name> 命令新建 Markdown 文件时, 会对应生成同名文件夹, 存放该文件的图片等资源.

   但问题没有被完全解决, 此时在 Markdown 文件引用图片时, 必须以 ![图片](<post_name>/123.png) 的方式引用, 而不能直接 ![图片](123.png). 下面的"更改网址的组织步骤" 可同时解决该问题.

修改文章与网址的映射关系

默认情况每篇文章的链接为: “xxx.github.io/2019/01/01/标题”, 这种以标题为组织方式的链接有时候不太好, 以下改为以 CRC 码为组织方式.

1. 在 Hexo 站点文件夹下打开 Git Bash, 输入:

   npm install hexo-abbrlink --save 
   

2. 打开站点配置文件 _config.yml, 修改:

   # URL
   ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
   url: http://yoursite.com
   root: /
   permalink: posts/:abbrlink.html
   permalink_defaults:
   abbrlink:
     alg: crc16
     rep: dec
   

   此后每篇文章链接为: “xxx.github.io/posts/12345.html”. 同时, 也可以直接用 ![图片](123.png) 来引用图片了.

开启 LaTeX 公式并修复默认公式渲染的 Bug

1. 默认 Next 主题不渲染公式. 开启渲染如下:
   打开 Next 主题的配置文件 _config.yml, 修改:

   mathjax:
   enable: true
   per_page: false
   cdn: //cdn.bootcss.com/mathjax/2.7.1/latest.js?config=TeX-AMS-MML_HTMLorMML
   

2. 此时发现, 对于多行的公式, 如:

   $$
   \begin{aligned}
   a^{[i+1]} & = z^{[i+1]} \\
   & = w^{[i+1]}a^{[i]} + b^{[i+1]} \\
   & = w^{[i+1]}(w^{[i]}a^{[i-1]} + b^{[i]} + b^{[i+1]} \\
   & = (w^{[i+1]}w^{[i]})a^{[i-1]} + (w^{[i+1]}b^{[i]}+b^{[i+1]}) \\
   & = w'a^{[i-1]} + b'
   \end{aligned}
   $$
   

   $$\begin{array}{rl}{a}^{[i+1]}& =z^{[i+1]}\\ & =w^{[i+1]}{a}^{[i]}+b^{[i+1]}\\ & =w^{[i+1]}(w^{[i]}{a}^{[i-1]}+b^{[i]}+b^{[i+1]}\\ & =(w^{[i+1]}{w}^{[i]})a^{[i-1]}+(w^{[i+1]}{b}^{[i]}+b^{[i+1]})\\ & =w^{\prime }{a}^{[i-1]}+b^{\prime }\end{array}$$
   渲染出来全挤在一行. 那肯定是不行的.

   试过别的方法如 hexo-renderer-markdown-it-plus, hexo-math, 都不好用. 最好用的还是下面这个:

   首先安装 Pandoc (Pandoc 官网), 然后执行下述指令以替换自带的 Renderer.

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

   目前来看还不错.

自定义非 Hexo 页面

例如我想在 xienaoban.github.io/demo/ 下新建自定义一些网页, 希望 demo 文件夹下的所有网页不受 Hexo 框架影响.

在 Hexo 站点目录打开 Git Bash, 在 source 文件夹下新建 demo 文件夹:

hexo new page demo

在 source/demo/ 下建立想要展示的 html 文件.

修改站点配置文件 _config.yml:

skip_render: demo/**

生成, 运行, Hexo 会将这些 html 直接复制到 public 文件夹下而不加以处理.

令 Next 主题默认展开所有子目录

打开 Next 主题下的 source/css/_custom/custom.styl, 添加一行

.post-toc .nav .nav-child { display: block; }