利用 Hugo 建立静态博客并通过 GitHub Pages 部署
Assumptions about Audience
本「教程」乃为女友之便所写，故
- 假设阅读者具有使用命令行工具的基本能力。（或许有帮助：Learning the Shell）
- 假设操作环境为 macOS Mojave/Big Sur。
Pre-requisites
安装 Homebrew
Homebrew 是 macOS 广为流行的包管理器。我们使用它来安装 Git、Hugo 及更多工具。
很便利地就可以安装它：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装 Git
Git 是一个分布式版本管理工具，我们使用它来管理项目（在此例中也就是博客）版本。
使用前步骤安装的 Homebrew 安装它：
brew install git
注册 GitHub 帐号并添加 SSH Key 到账户
GitHub 是一个用以支持版本管理和合作开发的代码代管服务平台。我们需要用它来存放站点文件以及使用它的 GitHub Pages 服务来发布我们的博客。
Join GitHub - Create your account
如果此前未生成过 SSH Keys（可以检查），生成新的 SSH Key 并加入 ssh-agent。将 SSH Key 加入 GitHub 账户。
创建 GitHub Repositories
在此步骤中我们需要创建两个 repos，一个用来通过 GitHub Pages 部署静态博客，一个用来储存站点源文件。
- 创建一个用来部署 GitHub Pages 的 repo，命名为
<USERNAME>.github.io。 - 创建一个储存站点源文件的 repo，命名为
blog。
初次运行 Git 前的配置
为 Git 配置用户名和邮件地址：
git config --global user.name "<USERNAME>" # GitHub username
git config --global user.email <EMAIL> # GitHub 注册邮箱
准备域名（Optional）
如要使用定制域名（custom domain），可参考 tld-list.com/ 挑选并购买域名。
此处假设我们购买了域名，并已通过 Let’s Encrypt 或 Cloudflare Free SSL/TLS 等途径为其获取了 SSL 证书（如果不确定的话可以检查）。
安装 Hugo 并在本地启用
安装 Hugo
brew install hugo
检查安装是否成功以及其版本：
hugo version
得到类似的结果说明安装已经成功，并指示了 Hugo 的版本：
Hugo Static Site Generator v0.80.0-792EF0F4/extended darwin/amd64 BuildDate: 2020-12-31T13:44:15Z
生成站点文件
cd ~/Documents # 这里我们将 blog 目录放置在 Documents/ 下，请按需修改
git clone [email protected]:<USERNAME>/blog.git
首先 clone blog repo 到本地。
hugo new site hugo_tmp
cd hugo_tmp && cp -R . ../blog && cd .. && rm -rf hugo_tmp
生成站点文件，并将站点文件转移到其中，这样我们就获得了一个存放站点文件的本地 repo blog。
接下来的操作（命令）主要都是以 blog 目录为根基执行，以 . 表示，比如 ./data 代表 blog 目录下的 data 目录。相关文档中，如果看到 site’s root 或 project’s root 等等都指的是此站点目录。
添加主题
这里使用女友选中的主题 Hello Friend NG 作为例子，可以到 themes.gohugo.io/ 或者按照项目 Git Stars 排序的 hugoranked.com/ 处查看更多的 Hugo 主题。
从 GitHub 获取主题，以 submodule 形式添加到 ./themes 目录：
cd blog
git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng
修改站点配置
将主题提供的模板站点配置复制到站点根目录：
cp themes/hello-friend-ng/exampleSite/config.toml .
为了后续使用 GitHub Pages 发布，我们需要修改 config.toml 中 baseurl 的值。
如果准备直接使用 <USERNAME>.github.io 作为域名，将 baseurl 的值修改为 https://<USERNAME>.github.io 。如果准备使用定制域名，将 baseurl 的值修改为 https://<YOURDOMAIN> 或 http://<YOURDOMAIN>（如果域名没有 SSL 证书）。
可能还需要按自己的需求修改其他的值，例如 title、name 之类。
创建文章
hugo new posts/my-first-post.md
新文章（名为 my-first-post.md 的 Markdown 文件）会被创建在 ./content/posts 下。
写入一些内容：
echo "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." >> content/posts/my-first-post.md
本地启动 Hugo 服务器
hugo server -D # -D 令 drafts 在编写与校对中可见。后续将站点部署上线，drafts 不会出现在 posts 中。
可在 http://localhost:1313/ 于本地查看站点页面、修改并实时观察变动。按下 Ctrl + C 中止。
撰写文章
编辑 Markdown 文件
推荐使用 Typora 编辑器，它移除了预览窗口，主打的特性是无缝（从 syntax 转换到样式文本）、所见即所想的编辑体验。
Front Matter
front matter 出现在每篇文章的开头，允许你将 metadata（比如 categories、date、tags、title）附在内容文件之中，Hugo 通过这些信息生成、组织、归类你的文章。
它可以由四种不同的格式完成，这里我们以 yaml 格式为例。yaml 格式的 front matter 以 --- 包裹。将以下代码放在文章（Markdown 文件）的最开头将给文章提供 metadata，不同的 front matter variables 提供的信息可查看具体说明。
---
categories:
- Tech
- Programming
date: "2020-12-21"
slug: why-ruby-is-the-best-pl
tags:
- ruby
- programming-language
title: Ruby is Best
---
注意，通过 hugo new posts/... 生成的新文章已经包含了默认的 front matter，你可以直接进行增添及修改。
部署到 GitHub Pages
准备事项
将此前生成的 public 目录删除：
rm -rf public
将我们作为 GitHub Pages 部署的 repo clone 到本地，命名为 public。这样后续使用 hugo 生成的静态文件将全部存放在此目录，并且拥有一个 remote origin 指向我们的 GitHub Pages repo。
git submodule add [email protected]:<USERNAME>/<USERNAME>.github.io.git public
如果使用 custom domain 的话，需要将域名写入 CNAME 文件并将其放置在 GitHub Pages repo 之中：
echo "<YOURDOMAIN>" > static/CNAME
同时，在 DNS 管理中添加一条 CNAME record：
Name: <YOURDOMAIN>
Content: <USERNAME>.github.io
脚本化发布流程
完整的发布步骤需要执行好几条命令，所以我们将其放在一个脚本中，并在之后的部署中直接调用它。
首先创建一个脚本 deploy.sh，并将它通过相应的应用打开（可能是 TextEdit 或其他文本编辑器）：
touch deploy.sh
open deploy.sh
将以下代码粘贴到其中：
#!/bin/sh
set -e # If a command fails then the deploy stops
printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"
hugo # Build a site to the ./public directory
cd public
git add . # Add all changes to git
# Commit changes
msg="Rebuild site $(date)"
if [ -n "$*" ]; then
msg="$*"
fi
git commit -m "$msg"
# Push source and build repos
git push origin master
# Commit all changes of project files and push
cd ..
git add .
git commit -m "Update blog files"
git push origin master
最后，给予 deploy.sh 可执行权限：
chmod +x deploy.sh
发布
每次需要发布，通过执行 deploy.sh：
./deploy.sh
如果你有额外的 commit message：
./deploy.sh "<YOUR OPTIONAL COMMIT MESSAGE>"
如此，我们每一次执行「发布」，public 内文件将被推送至 GitHub Pages repo，然后新版本的博客将会被部署。随后，blog repo 将会存放你新的站点文件，这方便于备份以及在新的工作环境中重新创建并启用一个博客目录。