使用 Github + Hexo 搭建个人博客

Github Pages 是利用 Github 仓库创建的展示页面，可以直接用来部署博客系统。Hexo 是一个很有名的静态博客框架，Next 是基于 Hexo 的一个博客主题。通过 Github Pages + Hexo + Next，可以快速搭建一个属于我们自己的博客系统。

前言

作为本站的第一篇文章，当然是介绍本站是如何搭建的啦！

和网上大部分的教程一样，本站使用 Github Pages + Hexo + Next theme 搭建。其实并没有什么工作量，都是前人做好的工具，我们无非就是把工具放在一起罢了。

准备工作

注册一个 github 账号

为了让别人可以访问我们的网站，必须将我们的网站部署到服务器上而不是在本地；但我们并没有自己的服务器（大部分人），所以一种很实惠又方便的做法是将我们的网站部署到 github 上，由 github 来托管我们的项目，并提供一个可访问的 url。每个 github 账号可以创建多个 github Page 仓库，每个仓库都是一个个人网站，这个仓库里的内容就是我们托管在 github 上的网页。

注册 github 账号没什么好说了，只要你有一个邮箱就行，打开 Github，点击 sign up，然后按要求一步步输入信息即可。

安装 git 客户端

github 是一个代码托管平台，使用 git 版本控制系统来管理代码，因此我们要在自己的电脑上下载一个 git 客户端，可以是图形界面也可以是命令行工具。常用的 git 客户端有 github desktop 和 git bash，没有好坏之分，看你喜欢用哪个，这两个客户端安装的时候都可以选择安装图形界面和命令行终端，建议终端必须要装。

配置 git 环境

安装完 git 客户端之后，还需要进行一些环境配置。最常见的就两步，添加 ssh 密钥和配置账号信息。

添加 ssh 密钥，首先要在本地生成一对 ssh 密钥，包括一个公钥和一个私钥，私钥存放在本地计算机，公钥拷贝到你的 github 账号上；然后每次访问 github 仓库时只要本地使私钥生效，就无需输入用户名和密码，因为使用的是 ssh 协议，只要本地私钥和远程公钥对应上就行。也可以不添加 ssh 密钥，这样的话就只能以 http 协议去访问 github 仓库，安全性没有使用 ssh 协议高，而且每次操作都得输入用户名和密码。

配置账号信息是指在本地的 git 配置文件中指明你的身份，这个身份包括一个邮箱和一个用户名，提交修改到远程的时候需要用到这些信息，否则远程仓库不知道你的身份，不知道这次修改是谁提交的。

关于 git 和 ssh 的更多信息可以参考网上的教程，也可以看我的这篇文章。因为这不是这篇文章的重点，所以在这里就不深入说了。

安装 node.js

如果只是想搭建一个个人网站，这一步并不是必需的。但因为我们想要搭建一个个人博客，即将我们的网站设计成一个博客系统，所以需要用到前人做好的优秀博客框架，比如下面要介绍的 Hexo 博客框架（当然，前端大神完全可以自己手撸，但对于像我这种不懂前端的，还是站在巨人的肩膀上吧）。而下载 Hexo 需要用到 Node.js，所以我们需要先将 Node.js 准备好。同样，安装工作没什么好说的，直接去官网下载一个和操作系统匹配的版本安装即可。

创建 github pages

github pages 就是我们在 github 展示的个人页面，github pages 其实就是一个 github repository，只是这个 respository 的命名比较特殊，要求是 name.github.io，只有以这个形式命名的仓库才会被当成 github pages，这里的 name 最好写我们的账号用户名或组织名，原因下面再讲。

首先，创建一个 github 仓库。点击 New repository 按钮（点击右上角的加号就会弹出），然后分别填写仓库名，添加仓库描述，设置项目公开或私有，是否以 readme 文件初始化仓库，是否添加 .gitignore 文件，是否添加 license 文件，最后点击 Create repository 按钮即可。除了仓库名，其它都是可省略的，但仓库描述最好写一下。

创建成功之后就可以通过 https://name.github.io 来访问我们的网站。 下面是几点要注意的事项：

• 再次重复一下仓库名必须是 name.github.io，只有这种格式的仓库才会被 github 当成 github pages。

• 仓库的 private 和 public 只是设置仓库代码的私有性，即别人是否能克隆修改我们的代码；发布的网站都是公开的，否则这个网站就没意义了。

• 关于仓库名中的 name，网上很多教程说只能使用我们的账号名 username，其实不然，这个名字是可以随便起的，只是取不同的名字会有些区别。

如果仓库名是 username.github.io，则可以直接通过 https://username.github.io 来访问我们的网站；
如果仓库名是 orgname.github.io，也可以直接通过 https://orgname.github.io 来访问我们的网站，这里的 orgname 指的是组织名 Organization，而且这个仓库必须是这个组织的仓库。比如我们有一个 Organization 叫 MyStudio，然后在这个 Organization 下面创建一个 Repository，也叫 MyStudio，则可以直接通过 https://MyStudio.github.io 来访问我们的网址。但如果仓库 MyStudio 属于这个账号而不是这个组织，那就不能以这种方式直接访问了；
如果仓库名不和用户名一致（用户的仓库），或者仓库名不和组织名一致（组织的仓库），则必须通过 https://username.github.io/xxx.github.io 或 https://orgname.github.io/xxx.github.io 来访问。很长也很不好看是不是，这就是上面说的最好以用户名或组织名来命名仓库原因。

因此，仓库名（这里说的仓库名是指前缀 name 部分，不包含后面的 .github.io）有两种命名方式，一种是跟用户名或组织一致，另一种则是不一致，我们姑且把和用户名或组织名一致的命名名方式叫做“直接方式”，不一致的叫做”间接方式“。

• 仓库创建完成之后，这时候访问我们的网址，可能会得出 404 错误；这是因为没有指定 github pages 的 source 分支，但这并不是一定会出现，有些仓库会有些不会。为什么呢？还是仓库名的原因。

如果仓库名是以“直接方式”命名的，则仓库自动指定了 master 分支为 github pages 的 source 分支，而且不能更改，所以这时候直接去访问是可以访问的；
如果仓库是以“间接方式”命名的，则默认是没有指定 github pages 的 source 分支的，所以这时候直接去访问就会报 404 错误。

对于“间接方式”命名的仓库，需要我们手动去设置 github pages 的 source 分支；打开仓库，点击 Settings，找到 Github Pages 分页，可以看到 source 下面是一个 none；

这时我们手动选择一个分支，并点击 Save 按钮即可。注意，只能选 master 或 gh-pages 分支，其实选项里就没有别的分支可选，如果没有这两个分支，就先创建分支（默认 master 分支一定有的）。具体的可以看 github 的官方文档 github pages。保存之后，就可以看到 github pages 可用了，而且访问地址也列出来，这里也可以看到访问地址并不是直接用的仓库名，而是用户名+仓库名。

安装 hexo

hexo 是一个流行的静态博客框架，安装 hexo 需要先安装 node.js 和 git 客户端；至于 hexo 的安装则非常简单，打开 git cmd，输入下面命令即可。

npm install -g hexo-cli

hexo 简单用法

关于 hexo 更详细的信息请参考官方文档 hexo 文档。

建站

首先，选择一个空文件夹作为我们博客存放的地方，然后在这个文件夹下右键打开 git cmd，输入下面命令，

hexo init
npm install

这样就把这个文件夹初始化为 hexo 的工作站，这步操作会把 hexo 的模板文件 clone 到这个文件夹下，可以看到主要目录结构如下：

- themes
- source
- scaffolds
- package.json
- _config.yml

• themes 文件夹下保存所有可用的主题，默认只有一个主题 landscape，我们可以下载别的主题，然后拷贝到这个文件夹下。
• scaffolds 文件夹保存文章的模板，使用 hexo new 新建文件的时候就会使用这个文件夹下的模板进行创建。
• source 就是存放我们文章的地方了，除了 _post 外，其它以下划线 _ 开头的文件夹或文件都会被忽略；生成的时候，这个文件夹下的 markdown 文件和 html 文件会被解析并放到 public 文件夹下，其它文件则被直接拷贝到 public 文件夹下。
• package.json 文件配置了已安装的程序，默认安装了 EJS, Stylus, Markdown render。
• _config.yml 则是 hexo 的配置文件，大部分参数都是这个文件配置的。

建完站之后部署到我们的 github pages，就可以 github pages 生成的 url 来访问我们的网站了。
首先，打开 _config.yml 文件，添加部署相关的配置，我们使用 git 来部署，填写 git 仓库地址和要部署的分支即可（上面说过 github pages 只能使用 master 分支或 gh-pages 分支，所以这里也只能部署到这两个分支）。

deploy:
  type: git
  repo: git@github.com:linjinxin/linjinxin.github.io.git
  brance: master

然后，安装 hexo-deploy-git，如果有多个站点，每个站点都得安装一次。在站点目录下打开 git cmd，输入 npm install hexo-deployer-git --save 即可。
最后，执行 hexo d -g 即可部署。
至此，网站就部署完了，因为我们没有添加任何文章，所以 Hexo 会自动添加一篇 hello-world.md 文章，所以打开 https://linjinxin.github.io，会看到这样的网页。

最后的最后，把网站变成我们自己想要的样子，通过换主题、修改配置，然后新增文章，修改文章，部署，不断地重复重复又重复，我们心目中理想的个人博客就有了。接下来介绍下 Hexo 的常用配置和常用命令，看看这个重复重复又重复的过程该怎么做。

配置

打开 _config.yml 文件，修改或添加下面的参数：

参数	描述	备注
tile	网站标题	显示在网站显眼的地方
subtitle	网站副标题	显示在网站比较显眼的地方
author	你的名字	在网站在显示作者的名字
description	网站描述	用于 SEO，告诉搜索引擎你的网站信息
language	网站使用的语言	中文或英文等，不是指开发语言，指定的语言必须是主题支持的
timezone	网站时区	默认为电脑的时区

更多参数请参考官方文档。

命令

• 建站 hexo init

• 新建文章 hexo new [layout] --path <filename> <title>

  新建文章的时候会根据指定的文章类型 layout 到 scaffolds 文件夹下对应的模板来创建文件，如果不指定 layout，则使用配置中的 default_layout；
  Hexo 定义了三种 layout：post, draft, page，也可以自定义 layout；

  • post 指默认的文章，使用这种 layout 创建的文章会放在 source/_posts 目录下。
  • draft 指草稿，使用这种 layout 创建的文章会放在 source/_drafts 目录下；草稿默认不会生成并显示在页面上，可以在生成的时候加上 --draft 参数或者在配置文件中设置 render_drafts: true，又或者使用下面将要介绍的命令将草稿变成正式文章。
  • page 则是创建其它的页面，比如在主页显示的标签页、分类页等，使用这种 layout 创建的页面会直接放在 source 目录下。
  • 在 scaffolds 目录下添加一个 mylayout.md 就可以添加一个 mylayout 的自定义模板，使用方法和别的模板完全一样，生成的文章也放在 source/_posts 下，所以可以认为自定义 layout 是 post layout 的一个扩展。

• 生成静态文件 hexo generate 或 hexo g

  参数 --deploy 或 -d：生成后立即部署；
  参数 --watch 或 -w：监视文件变动。

• 启动服务 hexo server 或 hexo s

  启动服务后，就可以在本地通过 localhost:4000 来预览我们的网站，这样就不用每次都部署到服务器才能看到效果；
  参数 --static 或 -s：只使用静态文件；
  参数 --port 或 -p：重设端口；
  参数 --log 或 -l：启动日志记录。

• 部署网站 hexo deploy 或 hexo d

  参数 --generate 或 -g：部署之前先生成静态文件；
  部署之前必须先在 _config.yml 中填写部署的相关配置，否则不知道该部署到哪里去。

• 把草稿发布成正式文章 hexo publish [layout] <filename>

• 从其它博客系统迁移内容 hexo migrate

• 清除缓存和已生成的静态文件 hexo clean

  有时候发现更改不生效的话，先执行这个命令再生成生成静态文件。

• 列出网站资料 hexo list <type>

• 显示 Hexo 版本 hexo version

一般的工作流程是 hexo init –> hexo new –> [hexo clean] –> hexo g –> hexo s(d)，即 建站–>添加文章–>[清理]–>生成–>调试(部署)。其实经常操作的就是后面两步，这两步可以通过参数简写成一步，即 hexo s -g，生成后启动服务，hexo d -g 生成后部署。

next 主题

Hexo 默认使用主题 landscape，如果你不喜欢这个主题，可以到网上下载别的主题，放到 themes 目录，然后在配置文件中设置 theme:<your-theme> 即可。我使用的是网上广泛使用的 Next 主题，下面简单介绍 Next 主题的功能。

主题的目录结构如下：

- language
- layout
- scripts
- source
- _config.yml

• _config.yml 主题的配置文件，和主题相关的配置都放在这里面；要注意的是在 Hexo 根目录下也有一个配置文件叫 _config.yml，这是整个站点的配置文件。
• language 语言文件夹，包含所有可用的语言包，在站点配置文件中配置的语言必须是这个文件夹中存在的语言。
• layout 布局文件夹，存放主题的模板文件，决定了网站的呈现方式，即整个网站是如何布局显示的。注意和 Hexo 中的 layout 区分开，前者是指创建的文章类型，而这里的 layout 才是布局的意思。
• scripts 脚本文件夹，存放主题执行的所有 javascript 脚本。
• source 资源文件夹，存放主题用到的所有资源，比如 css 文件，javascript 文件，字体，图片等。和 Hexo 根目录的 source 文件夹一样，这里的文件如果可以渲染的话，会经过解析之后放到 public 目录下，不能渲染的直接拷贝到 public 目录下；同样的以下划线 _ 开关的文件或文件夹会被忽略。站点的 source 文件夹和主题的 source 都是存放源文件的地方，不同的是前者存放的是我们编写的文章及文章用到的资源，后者存放的是主题内部用到的资源。

配置

看完主题的目录结构，我们知道主题的所有配置也在一个 _config.yml 文件中，这个文件可以配置的东西很多，接下来简单介绍下常用的配置，更详细的信息请访问官方网站 或者直接看配置文件。

参数	描述	备注
favicon	网站图标	显示在浏览器的标签页里
avatar	头像	有两个存放位置，站点的 source/uploads 目录下，或者主题的 source/images 目录下
footer/icon	页脚图标
footer/copyright	版权信息	不填默认为网站作者名
footer/powered	是否在页脚显示“由 Hexo 强力驱动”
footer/theme/enable	是否在页脚显示 Next 信息
footer/theme/version	是否在页脚显示 Next 版本号
scheme	网页的展示方案	可选的方案有 muse, mist, pisces, gemini
sidebar/position	侧边栏的显示位置	部分方案可用，left 或 right
sidebar/display	侧边栏的显示方式	部分方案可用，post, always, hide, remove
hightlight_theme	代码的高亮主题	可选 normal, night, night eighties, night blue, night bright
font	可以分别为 global, headings, posts, logo, codes 设置字体和大小	建议使用 web 安全字体
index_with_subtitle	是否在主页显示副标题	部分方案可用，要在站点配置中填写副标题
seo	是否开启 seo	开启后网站上的标题层次结构将被更改，以便更好地进行 SEO 搜索
baidu_push	是否自动推送文章链接到百度	开启后可让别人通过百度搜到我们的文章
第三方插件集成：
social	关联外部链接
social_icons/enable	是否显示关联链接图标
social_icons/icons_only	是否只显示关联链接图标	隐藏文本
disqus/eanble	接入 disqus 评论系统	disqus 系统需要翻墙才能访问
disqus/shortname	注册 disqus 时填的一个全网唯一 id
设置菜单项：
menu	菜单项
menu_icons	是否显示菜单图标

菜单项

菜单项以 key: link || icon 的形式配置，key 是菜单的名字，显示的时候会从语言中找对应的翻译，link 是点击菜单项之后要跳转到的页面，icon 则是菜单项的图标。这里 link 跳转的页面默认是没有的，所以点击菜单项之后会在新页面看到一句错误信息 Cannot GET /tags/，所以我们要为每个菜单项创建一个新的页面，幸运的是 Hexo 已有现在的命令。之前说到新建文章的时候有三种 layout 可选，post 表示普通文章，draft 表示草稿，唯独 page 的用处不太清楚；而到了这里，page 的用处就很明了了，没错就是给我们创建除了主页和文章之外的其它页面。

比如我们要添加一个菜单项 categories(分类)，首先在命令行输入命令 hexo new page "categories"，会创建一个 source/categories 目录，这个目录下会有一个 index.md 文件，这就是分类菜单项点击之后要跳转到的页面，另外还有一个 index 目录，保存这个页面用到的资源（和普通文章一样）。index.md 创建的时候默认会添加文件头，包含标题和创建日期。

---
title: tags
date: 2018-10-29 15:14:57
---

我们可以继续编辑文件内容，将页面设计成我们的样子，比如添加一个页面类型，这样 Hexo 可以自动帮我们创建对应的功能，下面是分类页面的文件头。

---
title: 分类
date: 2018-10-29 15:14:41
type: "categories"
---

下面是标签页面的文件头。

---
title: 标签
date: 2018-10-29 15:14:57
type: "tags"
---

其它

显示图片

Markdown 可以直接解析显示图片，只需要提供一个链接即可，因此我们要先将图片上传到某个服务器上，然后再把 url 拷贝到文章中。github 没有专门上传图片的功能，我们可以自己找个仓库来上传图片，也可以找专门的 CDN 服务器来上传，比如 Cloudinary。另一种方式是把图片放在本地，Markdown 不仅可以解析 url，还可以解析文件路径，我们可以把图片放在本地，通过本地路径来加载图片。

理论上图片可以放在本地的任意位置，只要填写正确的文件路径即可。但为了让 Hexo 能够正确解析（其实就是把图片拷贝到发布目录，并让生成的 html 文件能够正确链接到），图片的存放位置还是有要求的。

第一种方式是使用绝对路径，这种方式把图片放在 source 目录下，然后在链接那里写 /...。比如可以统一把图片放在 source/image 目录下，则链接的写法是 ![text](/image/xxx.png)。 这种方式的图片在首页和文章都可以显示。

第二种方式是使用相对路径，这种方式创建一个和文章同名的文件夹，和文章放在同一层目录，图片则放在这个文件夹下，比如有一篇文章 source/_posts/test.md，则创建一个文件夹 source/_posts/test/，然后把图片放在这个文件夹下，通过 ![test](xxx.png) 就能直接找到。这种方式的图片只能在文章中显示，在首页无法显示。

Hexo 默认是不能使用相对路径来解析图片的，必须在配置文件中设置 post_asset_folder: true 才行，设置之后使用 hexo new 创建新文章的同时也会创建对应的文件夹。

显示流程图

通过安装插件 hexo-filter-mermaid-diagrams 来使我们的博客支持 mermaid 图显示。

1. 进入博客所在根目录，打开控制台，输入命令 npm install hexo-filter-mermaid-diagrams，如果没有错误会在 node_modules 目录下多出一个 hexo-filter-mermaid-diagrams 目录，表示安装插件成功了；
2. 打开站点配置 _config.yaml，在最后添加下面代码，

# mermaid chart
mermaid: ## mermaid url https://github.com/knsv/mermaid
  enable: true  # default true
  version: "7.1.2" # default v7.1.2
  options:  # find more api options from https://github.com/knsv/mermaid/blob/master/src/mermaidAPI.js
  # startOnload: true  // default true

3. 打开 themes/next/layout/_partials/footer.swin，在最后添加下面代码：

{% if theme.mermaid.enable %}
  <script src='https://unpkg.com/mermaid@{{ theme.mermaid.version }}/dist/mermaid.min.js'></script>
  <script>
    if (window.mermaid) {
      mermaid.initialize({theme: 'forest'});
    }
  </script>
{% endif %}

4. 网上有文章说要修改站点配置 _config.yaml 中的 external_link: false，不过我试了不需要，如果你显示不成功不妨试一一下；
5. 最后，重新生成，hexo clean --> hexo g --> hexo s/d，执行清理、生成、部署，就可以看效果了，注意这三步缺一不可，尤其是后面两步，一开始我没执行 hexo s，所以一直看不到效果。

修改样式

打开 themes/next/source/css/_custom/custom.styl，添加对 mermaid 样式的定义，比如下面的样式将流程图的背景设置为透明。

.mermaid {
 background: transparent;
}

修改主页

默认主页会显示所有文章的完全内容，但更多的时候我们想只显示文章的摘要，有三种方式来修改主页的显示。

1. 修改主题配置 theme/next/_config.yaml，找到 auto_excerpt 选项，设置 enable: true 即可开启摘要显示，length 为要显示的字符数量。

2. 在文章中加入一行 <!-- more -->，则在这一行前面的内容会显示在首页摘要中，这一行后面的内容则不会显示首页摘要。

3. 在文章标题栏中添加字段 description: xxx，标题栏的东西是文章的标题部分，所以 description 的内容在文章的详情页中显示在标题下面。

第一种方式不推荐使用，这种方式是所有文章都显示固定的字符数，不好控制，而且显示的内容也不是文章的摘要部分。第二种方式和第三种方式差不多，都是要我们为每篇文章单独写个摘要，不同的是第二种方式摘要的内容在打开文章后会显示为正常内容，而第三种方式摘要的内容则在打开文章后会显示在标题栏，根据自己的需求选择第二种或第三种方式。

如果选用第三种方式，可以把 description 字段加入到文章的模板中，即修改 scaffolds/post.md 的内容如下：

---
title: {{ title }}
date: {{ date }}
tags: []
categories: 
description: 
---

显示背景动画

next 主题默认提供了一个花里胡哨的效果，就是在页面背景显示一个几何动画，开启这个动画很简单，打开主题配置 theme/next/_config.yaml，设置 canvas_nest: true 即可。注意配置文件里有两个 canvas_nest 配置项，第一个原来的内容是 canvas_nest: false，将这个改为 true，另一个原来的内容是 canvas_nest:，这是用于配置具体的动画效果的，默认不填读的是 theme/next/source/lib/canvas-nest/canvas-nest.min.js。