通过hexo + NexT + github pages + 搭建个人博客(一)

发表于 更新于 分类于 ， 阅读次数：

之前一直用各种笔记记录应用记录自己的学习过程. 由于只给自己看, 所以都是比较潦草的想到哪记录到哪. 但一旦碰到过已经记录的问题时, 很少去翻自己的笔记, 原因一是公司屏蔽内网屏蔽了好多这种笔记, 另一个是大部分google起来也很容易, 查看自己写的潦草的笔记还不如google一个优秀的技术博客来得快.

但最近我想给自己点压力, 把学过的内容整理成完整的文章. 尽量详尽. 即便没有别人读, 将来也可以留给我儿子看:). 争取把前因后果和自己的思考过程交代清楚, 而不是只有技术要点的bullet. 因为我发现网上能帮助到我的别人的博客, 往往都是这种写的很罗嗦的文章.

这篇作为第一篇, 就讲讲这个博客是怎么搭建起来的.

需求

我自己给要搭建的博客定了如下一些需求:

  1. 能够使用markdown语法编辑博客内容.
  2. 能够快速发布到网站.
  3. 支持文章中的代码片段语法高亮.
  4. 支持数学公式.
  5. 支持分级标签.
  6. 支持搜索.
  7. 尽量少的网站管理工作.

方案

根据这个需求我开始在google一顿狂搜. 最后决定的方案就是如同标题. 下面分别解释一下这几个都是什么.

  • Markdown: 一种轻量级标签语言, 其目标是纯文本的源文件是人类可读的, 但是有一定程度的结构化, 可以很容易转换成机器可读的html或者LeTeX. 人类可读可以让非技术人员也可以轻松使用, 结构化可以让电脑可以很容易解析. 能结合这两点的方案基本只有这一个, 没有别可替换的方案. 当然也可以直接写LeTeX和html, 但都无法让源文件是人类可读的, 对于写博客来说太重了.
  • hexo: 一个博客框架(framework), 可以把markdown写作的源文件渲染(render)成静态的html页面. 写博客的人其实只想书写博客的内容, 但是却很贪心的想要让这些内容更加优美的显示出来. 字体选择, 排版, 打标签, 分类, 搜索等等这些一个博客必要的因素都可由hexo框架帮助完成. 这种类型的框架有很多选择. 比如hugo和jekyll, 点击这里可以看到它们比较. 根据这篇文章, hexo的优点一个是快, 一个是基本没有什么缺点, 唯一的缺点是很多文档是中文的:). hexo这个框架作者好像是个台湾大学生, 使用node.js开发的.
  • NexT: 这是hexo的一个主题(theme), 也是github上点赞最多的一个. 页面精美简洁, 非常喜欢. hexo的一个特点就是可扩展性强, 很多插件(plugin)和主题可选.
  • github pages: 这个是github提供的一个静态页面托管服务. 免费稳定, 不管是国家还是公司都应该不会墙掉它. 只要把hexo渲染出来的静态页面上传到这里托管, 公网上就可以直接访问.
  • mathjax: 这是一个开源的javascript库, 可以把TeX格式的数学公式在网页上渲染成人类可读的数学公式. 这个其实不需要安装, NexT可以直接支持. 但有一些坑, 我稍后会讲.

实施

hexo

前提

安装hexo, 有两个前提一个是git, 一个是note.js. 这两个的安装基本就是下载安装文件, 双击打开, 不停点next就好了. 截止于写这篇文章的时候, 我机器上安装的版本分别是 

1
2
3
4
5
6
$ node -v
v10.9.0
$ npm -v
6.2.0
$ git --version
git version 2.17.1.windows.2

安装hexo

之后只要按照hexo官网首页上的提示运行下面命令就可以安装hexo 

1
$ npm install hexo-cli -g
安装完可以通过下面的命令查询一下安装的版本 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ hexo version
hexo-cli: 1.1.0
os: Windows_NT 10.0.15063 win32 x64
http_parser: 2.8.0
node: 10.9.0
v8: 6.8.275.24-node.14
uv: 1.22.0
zlib: 1.2.11
ares: 1.14.0
modules: 64
nghttp2: 1.32.0
napi: 3
openssl: 1.1.0i
icu: 62.1
unicode: 11.0
cldr: 33.1
tz: 2018e

初始化博客网站

继续按照官网文档执行下面这些命令 

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

其中folder是你博客网站的根目录. 如果当前目录就是根目录, 可以省略. 注意最后一条命令不能省略.

这时候系统默认有一片hello world的博客, 你可以通过 

1
$ hexo server
在本地启动一个端口为4000的web server, 直接访问http://localhost:4000查看这个hello world页面.

之后要做的就是修改配置, 然后就可以通过一些hexo命令创建新的博客了, 这里可以参考官方文档的配置和命令两个章节.

修改配置文件的时候, 注意设置语言和时区的时候注意大小写敏感, 我的设置如下: 

1
2
language: zh-CN
timezone: Asia/Shanghai

新建博客文章

根据官网帮助, 使用new命令可以新建一个博客, 但官网关于命令中的layout说得不是很明白. layout默认可以有3种可能: post, page and draft. 命令里省略layout就使用默认值post. 

1
$ hexo new [layout] <title>

post

一个post就是一篇普通的博客文章, 运行完这条命令你就可以在source\_post下找到这个后缀为md的文章, 使用markdown语法编辑你的文章就成为了源文件.

注意这个源文件最开头有个由三横杠---分割出来的头部, 里面包含一些关于这篇文章的属性信息, 你可以在官方文档里找到所有可以设置的元素.

这里有两个要特别说明一下, tags和categories. 这两个都可以理解对文章的关键属性打标签. 不同点是, tags是纯粹的标签, 跟文章是多对多的关系. categories是一个具有树状结构标签(所以也可以理解成分类), 每篇文章只能是这棵树的一个叶子节点. 例如我这篇文章的头部如下: 

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 通过hexo + NexT + github pages + 搭建个人博客
tags:
  - hexo
  - NexT
  - github
categories:
  - 技术
  - 杂项
author: Mingjian
date: 2018-09-02 23:12:00
---
其中对文章的分类是 
1
2
3
技术
 \_杂项
    \_搭建个人博客

这个是我个人认为最好的一种组合, 既有灵活的tags, 又有结构化的categories, 可以更好的组织整理自己的知识.

draft

顾名思义, 这是草稿, 你可以用hexo new draft <blogname>命令生成一个新的草稿. 之后就可以在source/_draft下找到这个markdown文件了. 既然是草稿, 就说明还没完成. 作为博客框架应该提供预览功能, 和一键发布的能力. hexo当然没有让我们失望.

  • 不论你用hexo g进行html渲染还是用hexo d部署, 或者用hexo s在本地运行server你都无法看到这个草稿的静态网页形式, 它只以markdown形式的源文件保存在本地.
  • 一旦你完成了草稿, 可以用hexo publish来发布文章.
  • 发布之前, 如果你想预览可以通过dexo g --draft和hexo s --draft在本地预览.
page

如果使用hexo new page <pagename>可以生成单独的页面, 通过http://localhost:4000/pagename来访问. 这个官网没有说得很明白这个是用来干嘛的, 我的理解是, 可以用来生成一些帮助组织博客站点的单独页面. 比如下面两个页面是NexT必须要生成的.

1
2
$ hexo new page categories
$ hexo new page tags

运行之后可以看到下面两个文件夹被生成, 并且添加一个只有头部的index.md文件. 然后在source\categories\index.md的头部里添加元素type: categories, 添加完之后文件变成这样.

1
2
3
4
5
---
title: categories
date: 2018-09-03 01:59:55
type: "categories"
---

同理, 在source\tags\index.md里添加type: tags 效果就是下面两个高亮的可以点击了.

安装NexT

可以按照官方安装帮助

可以使用git或者npm安装, 用npm最方便.

1
npm install hexo-theme-next@latest

注意Next有4种不同的页面搭配(scheme), 你可以去官方readme了解. 我选择了Pisces. 去配置文件_config.next.yml里修改一下即可 

1
scheme: Pisces

支持数学公式

NexT是内置了支持数学公式的, 但这里几个坑. hexo默认的markdown渲染器是hexo-renderer-marked, 但根据NexT的关于数学公式的文档. 里面提到如果在配置文件里激活对数学公式渲染的支持, 必需把这个默认的渲染器换掉. 如果你把公式渲染配置成Mathjax, 就必须用hexo-renderer-pandoc来作为markdown渲染器. 如果你用Katex, 就必须用hexo-renderer-markdown-it或者hexo-renderer-markdown-it-plus.

我的选择就是使用Mathjax + hexo-renderer-pandoc. 这里面还有个坑就是, 这个渲染器依赖pandoc这个软件, 必须先去pandoc官网下载安装一个pandoc. 下面是我安装的版本. 

1
2
3
4
5
6
7
8
9
$ pandoc --version
pandoc 2.2.3.2
Compiled with pandoc-types 1.17.5.1, texmath 0.11.0.1, skylighting 0.7.2
Default user data directory: C:\Users\e323819\AppData\Roaming\pandoc
Copyright (C) 2006-2018 John MacFarlane
Web:  http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

之后就可以通过下面的命令替换掉渲染器. 

1
2
npm un hexo-renderer-marked --save
npm i hexo-renderer-pandoc --save

然后到_config.next.yml里修改打开对数学公式的支持.

1
2
3
4
5
6
7
# Math Equations Render Support
math:
  enable: true
  per_page: false
  engine: mathjax
  mathjax:
    cdn: //cdn.jsdelivr.net/npm/mathjax@2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML

per_page这个变量如果是false, 渲染时每篇都会把mathjax加载到页面里, 如果是true, 那么只有页面头部包括了元素mathjax: true才会加载.

这样配置以后试试在你的博客里加入数学公式, 比如如下公式: 

1
$$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}\tag{displayed}$$
会生成 \[\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}\tag{displayed}\]

本地贴图

如果使用网络里的图床, 只需要用相应的markdown语法链接一下就行了. 但如果想要使用本地图片, 有这么几个解决方案.

  1. 把图片放在source/img下, 然后在用markdown语法![img](/source/img/xxx.png)的形式. 缺点是所有博客的图片会混在一起, 不好管理.
  2. 配置_config.yml中的变量post_asset_folder: true, 这时一代你通过new命令建立一个新博客文章, 就会自动生成一个同名文件夹用来放置资源文件. 然后使用hexo专用的语法{% asset_img slug [title] %}. 这么做的缺点是你的markdown文件将不能在别的地方被解析.
  3. 跟2一样配置_config.yml中的变量post_asset_folder: true. 然后用命令 
    1
    npm install https://github.com/CodeFalling/hexo-asset-image --save
    安装一个插件. 然后使用一般的markdown语法即可以显示. 
    1
    {% asset_img "img.jpg" "img" %}
    缺点就是要依赖于一个额外的插件. 我个人觉得一般来说写的博客不太可能迁移, 所以用hexo默认的方案2即可. 如果确实有迁移的需求就用3.

部署到github pages

到现在为止, 我们可以在本地生成非常漂亮的静态页面. 可以使用markdown, 可以渲染数学公式, 可以使用图片. 我们需要在公网上找一个地方放置我们的这些静态页面. 这个选择非常多. 我选择了github page. 原因是使用简单, 几乎不需花时间维护, 国内公司都没有被墙掉, 可信程度高.

这里我们假设你已经有github的账户了. 如果没有需要创建一个, 具体创建过程在这里省略. 假设账户名是xyz. 那么你只需要创建一个名字叫做xyz.github.io的新项目, 就完成了github上的操作.

之后需要在_config.yml里的deploy下面加下面的配置, 注意type前面那个-最好加上, 因为如果deploy西面有多个deployer的话, 没有这个横岗会报错. repo的值如果报错可以尝试把用户名和密码加上, 就像这样https://xyz:pword@github.com/xyz/xyz.github.io.git. 我在一台机器上碰到这个问题这么解决了, 但在别的机器上就不加也可以提示直接输入.

1
2
3
4
deploy:
- type: git
  repo: https://github.com/retzzz/retzzz.github.io.git
  branch: master

然后在你blog的主目录下安装一个git deployer插件.

1
npm install hexo-deployer-git --save

这之后只要使用下面任何一个命令, 都可以完成部署. 

1
2
3
hexo deploy
hexo d
hexo g -d

进阶

到这里一个初步的博客就搭建完成了, 我最开始提到的基础需求都得到满足. 但其实还有好多细节可以继续丰富, 我列出一些以后再有时间可以再写一篇进阶篇:

  1. 添加评论功能, 让用户可以对某一个文章进行评论.
  2. 文章访问计数.
  3. 各种社交网站的超链接.
  4. 为页面添加固定页眉页脚.
  5. 替换默认图标.
  6. 直接所见即所得的对markdown文档进行编辑.
  7. 博客内部文章的互相跳转.

总结

1
2
3
4
5
6
7
8
9
npm install hexo-theme-next@latest
npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-pandoc --save
npm install hexo-deployer-git --save
npm install hexo-asset-image --save
npm install hexo-image-link --save
npm install hexo-abbrlink --save
npm install hexo-generator-searchdb save
npm install hexo-include-markdown --save

请访问通过hexo + NexT + github pages + 搭建个人博客(二) -- plugin-tags

参考网页:

1 2 3 4 5 6