在 GitHub Pages 上搭建个人博客

创建 Github Pages

新建一个 GitHub 仓库，仓库名为 <username>.github.io，其中 <username> 是你的用户名（不是昵称）。

比如我的用户名是 “sainnhe”，那么新建的这个仓库就名为 sainnhe.github.io

接下来把它克隆到本地，并在项目的根目录创建一个文件：index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>My Blog</title>
</head>
<body>
  My Blog
</body>
</html>

Push 到 GitHub，过一会后从浏览器访问 sainnhe.github.io 就可以看到这个页面了。

自定义域名

我之前在 Google Domains 买了一个域名 “sainnhe.dev”，我想在 GitHub Pages 中用我自己的域名。

在项目的 Settings -> Options 界面找到 Github Pages，输入 www.sainnhe.dev 并保存。

这会在项目根目录下创建一个名为 CNAME 的文件并提交，所以弄完后要 pull 一下。

接下来进入 Google Domains，浏览到 DNS 的页面，在底部找到 Custom resource records，创建一个 CNAME 记录，指向 sainnhe.github.io：

CNAME

接下来让 sainnhe.dev 重定向到 www.sainnhe.dev，这通常是用 ALIAS/ANAME 记录来实现的，但 Google Domains 不支持这种记录，不过它提供了 Synthetic records 也可以实现同样的效果：

Synthetic

这里的 subdomain 填 @ 的话就会直接重定向 sainnhe.dev 这个二级域名。

配置 Publishing Source

有 index.html 这个文件的目录就可以当成一个 Publishing Source。在上面的例子中，sainnhe.github.io 这个仓库的 master 分支的根目录就是一个 Publishing Source。

除了直接用这个 GitHub Pages 的仓库作为 Publishing Source 之外，你还可以在其它的仓库中配置 Publishing Source。

比如你还有个仓库名为 myrepo，这个仓库的 master 分支下有个 /docs 目录，这个目录下有个 index.html，那么你就可以把它配置成一个 Publishing Source。

配置完成后，就可以在 https://www.sainnhe.dev/myrepo 访问了。

具体的步骤是在 myrepo 项目中的 Settings -> Options -> GitHub Pages 中选择 Source 为 master 分支的 /docs 目录。

如果你不想直接在 master 分支中放 Publishing Source，还可以创建一个分支来单独维护它。

这个分支有固定的名字 gh-pages，推送这个分支后，GitHub 会把它的根目录（而不是 /docs 目录）自动识别为 Publishing Source 的可选项，然后你就可以在 Settings -> Options -> GitHub Pages 中选择使用这个分支了。

使用 Hugo 生成静态网页

目前比较火的静态网页生成工具有 Jekyll, Hugo 和 Hexo，我比较喜欢 Hugo，主要是因为生成速度很快。

Arch Linux 官方仓库里就有 Hugo，所以直接用包管理器安装：

1

$ sudo pacman -S hugo

然后执行以下命令：

1
2
3
4
5
6
7


$ hugo new site blog # 创建一个新项目，名为 `blog`
$ cd blog
$ git init
$ git submodule add https://github.com/olOwOlo/hugo-theme-even themes/even # 使用 even 主题
$ cp -f themes/even/exampleSite/config.toml ./config.toml # 使用示例配置，待会直接在上面改
$ cp -rf themes/even/exampleSite/content/* ./content/ # 先用示例 markdown 文件试一下
$ hugo server # 直接从浏览器访问 localhost:1313/ 就可以看到效果了

Hugo 会读取 /config.toml 作为项目的配置，然后从 /content 里面的 markdown 文件生成静态网页文件，并放在 /public 下。

hugo server 不会生成 /public，要想生成静态网页文件，直接运行 hugo 命令。

接下来把 /public 下的所有东西复制到 sainnhe.github.io 下，然后 push 就行了。

更多用法，参考 Hugo 和 olOwOlo/hugo-theme-even。

GitHub Actions

每次改完 /content 都要生成 /public 再 push 有点麻烦，我们可以通过部署 GitHub Actions 来自动化这两个步骤。

在 GitHub 创建一个新的仓库 blog 用来放 Hugo 项目（可以是私有仓库）：

1
2


$ git remote add origin git@github.com:sainnhe/blog.git
$ git push -u origin master

生成一对 ssh key

1

$ ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

将会得到两个文件：gh-pages.pub（公钥）和 gh-pages（私钥），用文本编辑器打开可以看到文件的内容。

在 sainnhe/blog 项目主页中，找到 Repository Settings -> Secrets -> 添加这个私钥的内容并命名为 ACTIONS_DEPLOY_KEY

在 sainnhe/sainnhe.github.io 项目主页中，找到 Repository Settings -> Deploy Keys -> 添加这个公钥的内容，并勾选 Allow write access

这是我的 GitHub Actions 配置文件，仅供参考：

sainnhe/blog 仓库中新建 /.github/workflows/gh-pages.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: sainnhe/sainnhe.github.io
          publish_branch: master
          publish_dir: ./public
          emptyCommits: false
          commitMessage: ${{ github.event.head_commit.message }}
          cname: www.sainnhe.dev

注意不能用 run: hugo --minify，不然会有一些问题。

写完之后提交并推送，之后每当 push 到 sainnhe/blog 的 master 分支，就会自动生成 /public 并把它里面的文件推送到 sainnhe/sainnhe.github.io

除了创建一个新的仓库用来专门放 Hugo 源代码外，还可以在 sainnhe.github.io 创建一个专门的分支用来放 Hugo 源代码，然后通过 GitHub Actions 把这个分支中的 /public 推送到 master 分支的根目录，从而完成自动化部署。

更详细的介绍，参考 peaceiris/actions-hugo 和 peaceiris/actions-gh-pages。

评论系统

目前 Even 主题支持的评论系统包括：gitment, utterances, gitalk 以及 valine。

这四个里面除了 valine 之外都是基于 GitHub Issues 搭建的，我这里选择了 utterances。

首先，选择一个公开仓库用来放评论，我就直接用了 sainnhe/sainnhe.github.io。

接下来把 utterances 安装到这个仓库：utterances

然后在 /config.toml 里配置 utterances:

1
2
3


  [params.utterances]       # https://utteranc.es/
    owner = "sainnhe"              # Your GitHub ID
    repo = "sainnhe.github.io"               # The repo to store comments

注意，这里的 owner 填的不是 GitHub ID 而是 GitHub User Name，注释有一定的误导性。

Contents