This article talks about how to use Hugo to build a personal website hosted on Github Pages. It also introduces how to find a free custom domain name from Freenom and migrated the DNS server to CloudFlare in order to use HTTPs with chosen custom domain name on GitHub Pages.
本文讲述了如何使用Hugo将个人网页托管在Github Pages上。同时也介绍了如何在Freenom上找到免费个人域名并利用CloudFlare的免费DNS服务在Github Pages上以HTTPs协议加载个人域名。

前言

最开始写博客始于2015年末，当时因为自制了几个单簧管演奏的视频，心想可以建一个简易的网站把录制背后的故事和想法集合起来。由于个人网站一般不需要太多交互，使用静态网页生成器并托管在Github Pages上成为了首选方案（能使用git实现版本控制更是个加分项）。彼时没想太多直接用了Github Pages原生支持的网页生成器Jekyll。随便搜了一个主题，第一版网站便这么建了起来：

在为期一年断断续续的更新中总计写下了十余篇音乐和程序相关的（毫无营养的）文章后，第一代模板差不多也看腻了，突然觉得是时候该把网站升级下。遂决定新的博客应更简洁规整，首页加入图片预览功能并减去不必要的视觉干扰，菜单栏里应有分类、标签和归档功能。一番搜寻后，目光落在Hugo。主要原因在于Hugo简单易用——不需要安装太多Hexo中的依赖库，更换主题也比Jekyll方便，生成速度还很快。以下便是我的配置过程。

安装Hugo

本文在macOS High Sierra环境下写成。Windows平台可参考官方文档做相应修改。

如果Mac上已经装上了Homebrew，在命令行中直接敲下面的命令安装：

1

brew install hugo

如果Mac上没有安装Homebrew，可以考虑先装Homebrew再按上述步骤安装Hugo；也可以在Hugo官网直接下载使用可运行文件。

至此Hugo就安装完毕了。So easy.

在Hugo中写文章

在硬盘中选取合适的存储路径，然后命令行中使用如下指令生成网页本地文档：

1

hugo new site personal-site

由此可得到如下文件目录：

personal-site
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

常用目录用处如下

使用下面的命令生成新的文章草稿：

1

hugo new posts/first-post.md

在content目录中会自动以archetypes/default.md为模板在content/posts目录下生成一篇名为first-post.md的文章草稿：

---
title: "First Post"
date: 2017-12-27T23:15:53-05:00
draft: true
---

我们可以加一个标题在下面并去掉标记为草稿的这一行：draft: true

---
title: "First Post"
date: 2017-12-27T23:15:53-05:00
---

## Hello world

然后随便下载一个主题并加载到config.toml文件中：

1
2
3
4
5
6

git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

# Edit your config.toml configuration file
# and add the Ananke theme.
echo 'theme = "ananke"' >> config.tomlecho 'theme = "ananke"' >> config.toml

现在使用如下命令建立本地服务器：

1

hugo server

并在浏览器中输入网址http://localhost:1313/就可以在浏览器中查看网页效果了：

如果觉得没有问题了便可以使用如下命令：

1

hugo

如此一来网页便生成在默认的public子目录中了。

发布并托管到Github

上传到Github之前，先在Github中添加一个空白repository，注意不要添加如README，.gitignore等文档。由此得到Github中该repository的网址：https://github.com/Nianze/personal-site.git

复制该网址后，在网站本地文档根目录中初始化git：

1
2
3
4
5

git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/Nianze/personal-site.git
git push -u origin master

至此所有源文档就都push到Github上了。然而此时Github对待这些源文档跟其他任何普通的repository中的代码并没有任何不同，并不会将public子目录中的网页托管在Github Pages上。

参见Hugo官方文档，可以选择以下两种方式让Github Pages加载我们想要托管的/public子目录中的网页：

1. 配置Hugo将网页生成在名为/docs的子目录中，然后直接push到master branch
2. 仍然使用默认的/public子目录存储网页，再单独建立一个gh-pages branch

使用/docs发布到master branch

第一种方案的好处在于一次push即可将源文档和对应生成的网页文档都发布到Github，操作非常简单。所需要的仅是在config.toml中添加如下一行配置，使得生成的网页默认保存在/docs子目录下：

1

publishDir = docs

自此运行hugo命令后生成的网页文件将保存在/docs子目录下。将所有文档push到Github的master branch，进入Github对应repository的Settings标签菜单，在GitHub Pages选项的Source栏选择master branch /docs folder:

等待片刻即可访问http://your_name.github.io看到之前用Hugo生成的网页了。

发布到gh-pages branch

如果希望单独控制源文档和生成的网页文档的版本历史，可以使用单独建立一个gh-pages branch的方法托管到Github Pages——先将/public子目录添加到.gitignore中，让master branch忽略其更新，然后在本地和Github端添加一个名为gh-pages的branch：

1
2
3
4
5
6
7
8

//忽略public子目录
echo "public" >> .gitignore
//初始化gh-pages branch
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push origin gh-pages
git checkout master

为了提高每次发布的效率，可以将下述命令存在脚本中，每次只需要运行该脚本即可将gh-pages branch中的文章发布到Github的repo中：

 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

#!/bin/sh

if [[ $(git status -s) ]]
then
    echo "The working directory is dirty. Please commit any pending changes."
    exit 1;
fi

echo "Deleting old publication"
rm -rf public
mkdir public
rm -rf .git/worktrees/public/

echo "Checking out gh-pages branch into public"
git worktree add -B gh-pages public origin/gh-pages

echo "Removing existing files"
rm -rf public/*

echo "Generating site"
hugo

echo "Updating gh-pages branch"
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"

echo "Push to origin"
git push origin gh-pages

最后将master branch中的源文档和gh-pages branch中的网页文档分别push到Github repo中，进入Settings标签菜单，选择Github Pages项中的Source栏，点gh-pages branch选项：

同样等待片刻，即可访问https://your_name.github.io看到之前用Hugo生成的网页了。

配置个人域名

如果觉得使用your_name.github.io不够酷炫，还可以考虑使用自选的个人域名。好的个人域名自然是需要到对应服务商购买的。常见的域名如.com, .net, .me一般都不免费，但好在非顶级域名的年费其实也不贵。由于我建网的初衷只是自娱自乐，暂时并没有付费购买域名的意向，索性直接去Freenom找了免费域名来用。目前Freenom平台提供的免费域名后缀为.tk, .ml,ga,cf,gq等。购买域名很简单，先在Freenom
网站上注册账号，然后查看自己想要的域名的价格并根据提示下单即可。考虑到现在machine leanring这么火，我就选了nianze.ml这个免费域名。

域名买好后还需要设置下域名解析。由于默认使用的是Freenom的DNS服务器，所以需要在Manage Domain菜单中配置域名解析规则。在Manage Freeenom DNS选项中添加如下两条规则：

1. 添加A记录（即地址记录，用来指定域名的IP地址），主机记录（Name）栏填www，记录值(Target)那栏填Github服务器IP地址（或者your_name.github.io的IP地址）
2. 添加CNAME记录（用于将一个域名映射到另一个域名），主机记录栏填@，记录值那栏填your_name.github.io

其中，Github服务器IP地址是192.30.252.153和192.30.252.154，而your_name.github.io的IP地址可以在命令行中使用ping命令得到：

最后还需要在personal-site/public子目录中需要添加一个名为CNAME的文档，该文件只包含想要替换的个人域名，对我来说即是nianze.ml（不加http）。由于每次使用hugo命令
在/public子目录生成网页的时候该CNAME文件都会被删除，所以最好将该文件放在personal-site/static子目录中，这样运行hugo后该CNAME文件将自动复制到/public目录中。

等待几小时，在浏览器中访问nianze.ml就可以看到熟悉的个人网站页面了。

配置CloudFlare以使用HTTPs

之所以想要使用CloudFlare，是因为上一步当我们配置好个人域名后，由于Github Pages不支持在自定义域名中使用HTTPs协议，所以浏览器中访问nianze.ml使用的是HTTP协议。这造成一个弊端：每回用Chrome打开nianze.ml，浏览器都提示该网页不受信任，如果网页中还有待加载的JavaScript代码,就得单独点浏览器地址栏右侧的load按钮才能正常加载全部页面，非常麻烦。再加上考虑到HTTPs协议比HTTP更快更安全，显然应该想办法解决这个问题。

好在CloudFlare为我们提供了一套方便的解决方案，而且是免费的！

首先点开CloudFlare注册账号，输入前面选好的个人域名nianze.ml，CloudFlare会给我们提供众多服务套餐，选择免费的那个套餐即可:)

此时CloudFlare会给我们提供其DNS服务器的IP，此时需要去Freenom的域名管理页面中更新默认DNS服务商到CloudFlare：

更改完DNS服务器就可以设置CloudFlare中的各个选项了。首先在Crypto选项标签下，选择使用Full SSL模式以HTTPs协议加载网页：

然后是DNS标签栏配置，跟Freenom设置类似：

最后再设置下Page Rules标签：

至此配置完毕。其实CloudFlare中还有很多别的选项，可以根据个人喜好进行相应配置。等待几小时，再次访问nianze.ml，可以发现网页已经在HTTPs协议下加载了。这样以来就再也不用去点那个烦人的load按钮了。

后记

至此我的新版博客就迁移完毕了，基本满足我现在写文章、摄影和音乐的各项需求。下一步准备在摄影栏目中加上一个照片墙功能。

参考文档

1. Hugo Tranquilpeak Theme
2. Using HTTPs with Custom Domain Name
3. Deploy Hugo to Github