创建 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 就行了。

更多用法,参考 HugoolOwOlo/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-hugopeaceiris/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,注释有一定的误导性。