前言#
建立博客也有接近一个月的时间了，在此过程中，从开始时较为简陋的模板逐渐探索，现在也初见规模了。今天就将这一个月的经验总结一下，希望有所帮助。
Hugo 是由 Go 语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。更多介绍可以查看 官网 ，本文旨在介绍如何使用 hugo 和 github 搭建一个博客，并且部署一个主题。
我们的博客其实可以分为三个部分，一个是我们方便编辑的本地后端（git 库），一个是我们上传到网上的在线后端（github 库），还有一个是我们的博客前端（github pages），下面我们详细介绍一下各部分如何建立和联系。
0.准备工作#
- 安装 go
- 安装 git
- 安装 hugo
- （可选）安装 typora
注：本文所用环境为 Linux，在 Windows 或 Mac 上方法类似。
1.安装 go#
在 go 的 官网 下载安装包 go1.23.3.linux-amd64.tar.gz，之后输入：
tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz
解压到 /usr/local 目录。然后设置环境变量：
sudo gedit /etc/profile
在末尾加入 export PATH=$PATH:/usr/local/go/bin ，保存即可。
完成后我们在终端输入：
go version
如能出现 go version go1.23.3 linux/amd64 的结果，则证明安装成功。
2.安装 git#
在终端中输入：
sudo apt install git-all
安装完成后，输入：
git --version
如出现 git version 2.34.1 的结果，则证明安装成功。
3.安装 hugo#
在终端中输入：
sudo apt install hugo
安装完成后，输入：
hugo version
如出现 hugo v0.139.2-770f548b47b39e6f0fd4da1cc80552024e5829e1+extended linux/amd64 BuildDate=2024-11-23T15:33:51Z VendorInfo=snap:0.139.2 的结果，则证明安装成功。
4.（可选）安装 Typora#
Typora 是一款 Markdown 编辑器，能够十分方便的编辑 .md 文件并查看效果，这使得在 Linux 上编辑文章也十分方便。
在 Typora 的 官网 ，我们可以在页面底部找到 Linux 的 安装方法 。
先下载 typora_1.9.3_amd64.deb 文件，然后输入：
sudo dpkg -i typora_1.9.3_amd64.deb
进行安装。（也可以使用 apt-get 方式安装）
安装好后，需要进行激活，这里参考 此文章 进行激活，不再赘述。
5.建立 GitHub 后端库#
首先拥有一个 GitHub 帐号，登录之后，创建一个新的 repository ：
在 Repository name 中填写任意一个名字，作为后端库的名字（如 MyBlog ）。在 Private 前面勾选，表示该库是私有的。勾选 Add a README file ，表示添加一个默认的 readme.md 文件，这一步是为了便于后续 git clone 。
点击右下角 Create repository 后，我们就创建好了我们的后端库，这时后端库中只有一个 readme.md 文件。我们需要到后期配置好主题后，才会将它补充完整。
6.建立 GitHub 前端库（GitHub Pages）#
再创建一个新的 repository ，这里的 Repository name 要求必须是 你的GitHub用户名.github.io ，如图：
在 Public 前面勾选，表示该库公开。勾选 Add a README file ，这会设置 main 分支作为默认的主分支，这点在后续推送博客内容时十分重要。（也可以手动设置）
这里讲一下设置两个库的目的，其实后端库不是必要的，把所有内容一股脑放到前端库中也可以构建博客，但此时别人是可以访问到你的源文件的。也就是说，你的各项配置，文档图片，甚至未公开的草稿等都可以被人直接下载。
为了设置一点隐私性，我们在后端库中上传所有文件，将利用 hugo 渲染出的 .html 网页文件同步传输到前端库中。这样别人既能通过前端库看到我们的博客，又不能直接访问我们的源文件。
为了上传后可以自动发布，我们需要设置一下 GitHub Actions 功能。
在 GitHub 设置 界面找到 Developer settings ，点击 Personal access tokens 中的 Tokens(classic) ，点击右上角的 Generate new token ，选择 Generate new token(classic) 。
设置一个名字（这里假设为 HUGO ），勾选 repo 和 admin:repo_hook ，在 Expiration 选项选择 No expiration ，这样就不必频繁更新了。点击 Generate token ，并将显示的 token 复制下来保存好（只显示一次，如果不保存则后续需要重新设置 token）
接下来进入后端库的界面，如图：
找到右侧的 Settings ，点击后找到左侧的 Secrets and variables ，点击 Actions 。点击 New repository secret ，名称自取（这里假设为 HUGO ，与刚才的 token 名称无关），Secret 中填写刚刚复制保存的 token。
至此，我们只需要再设置好配置文件，就可以自动发布了，配置文件将在下一节创建。
7.建立本地 Git 后端库#
本质上来说，我们只要有后端库和前端库，博客就能生效。但是我们无法直接在 GitHub 上操作，因此需要在本地建立 Git 后端库，再将二者联系起来。
首先在本地建立一个文件夹，在此文件夹中，将在线后端库克隆到本地，此时出现一个 MyBlog 文件夹。
对 git 基础操作不了解的同学可以看这篇文章：
进入 MyBlog 文件夹，打开终端，输入：（ xxx 是网站目录，任取一个名字即可）
hugo new site xxx
可以看到出现了一个文件夹，名称为 xxx，里面有一些文件夹和文件。此时，我们的博客后端已经建成了。
这时我们进入该文件夹，创建一个 .github 文件夹，进入 .github ，创建一个 workflows 的文件夹，在该文件夹下，创建 gh-pages.yml 。
打开该 .yml 文件，粘贴以下代码（注意： external_repository 和 personal_token 需要修改）：
name: github pages
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest # 这里最好换成 ubuntu-22.04, 避免高版本不兼容
steps:
- uses: actions/checkout@v2
with:
submodules: true
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.139.4' #这里一般是 latest,但 0.139.5 暂时有问题
# extended: true
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
# github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
external_repository: DeathGarurumon/DeathGarurumon.github.io # 改成你自己的地址
personal_token: ${{ secrets.HUGO }} # HUGO 改成你的 secret 的名称
publish_dir: ./public # 发布public文件夹的内容
publish_branch: main # 发布到哪个branch
8.安装和配置主题#
Hugo 社区 提供了许多主题，每个主题都会有相关的安装文档。这里我们以本博客所用主题 Blowfish 为例，讲解一下安装过程。
Blowfish 比较贴心的一点是有详细的 中文文档 ，按照 安装教程 ，我们进入刚刚的网站目录，输入：
git init
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
此时主题文件就下载完毕了。
接下来我们将网站根目录的 hugo.toml 删掉，新建一个文件夹并命名为 config，在 config 中新建一个文件夹并命名为 _default 。
在网站根目录下，我们进入 /themes/blowfish/config/_default ，将里面的所有 .toml 文件都复制到刚刚我们新建的 /config/_default 中。
1.配置 hugo.toml#
打开 hugo.toml ，设置以下必要项：（若有注释，取消即可）
theme = "blowfish"
baseURL = "https://DeathGarurumon.github.io/"
defaultContentLanguage = "zh-cn" # 这里选择你的网站语言（主要和配置选择有关）
pluralizeListTitles = "true"
2.配置 languages.zh-cn.toml#
这里的文件名后缀要注意，需要与 hugo.toml 中设置的 defaultContentLanguage 保持一致，其它后缀的可以删除。
打开 languages.zh-cn.toml ，设置以下项目（主要是主页相关）：
languageCode = "zh-cn"
languageName = "简体中文"
title = "DeathGarurumon" # 这个是页面左上角的名称
[params]
logo = "img/author.png" # 页面左上角的logo，需要在对应目录下放置图片
[params.author]
name = "DeathGarurumon" # 主页的中心位置
image = "img/author.jpg" # 主页的logo位置
headline = " All work and no play makes Death a dull boy.
" # 这是座右铭的位置
links = [ # 这里可以添加主页上自己的链接
{ twitter = "https://twitter.com/username" }
]
3.配置 menus.zh-cn.toml#
这里的文件名后缀也需要与 hugo.toml 中设置的 defaultContentLanguage 保持一致，其它后缀的可以删除。
打开 menus.zh-cn.toml ，设置以下项目（这里是右上角和左下角的目录相关）：
[[main]] # main是指右上角
name = "文章" # 这里是目录名称
pageRef = "docs" # 这是目录对应的路径，位于 /content/docs
weight = 10 # 这里是位次的相对权重，weight小的会排在前面
[[main]]
name = "娱乐"
pageRef = "play"
weight = 15
[[main]]
identifier = "email"
pre = "email"
weight = 300
url = "mailto:deathgarurumon@gmail.com"
[[main]]
identifier = "github" # 这里是站外链接
pre = "github"
url = "https://github.com/DeathGarurumon"
weight = 400
[[footer]] # footer表示左下角
name = "标签"
pageRef = "tags" # 这里是自动建立，无需手动设置目录
weight = 10
[[footer]]
name = "分类"
pageRef = "categories"
weight = 20
这些设置后的效果大概是这样：
4.其他配置（ params.toml 等）#
params.toml 中都是一些个性化配置，可以边调边试，按照自己喜好配置。
9.本地预览#
在博客根目录打开命令行，输入：
hugo server
如果没有报错，就说明成功在本地建立了我们的博客网站。此时，我们可以在浏览器中访问 http://localhost:1313/ 来查看我们的博客。
如果遇到报错，通常是这种形式：
ERROR [zh-cn] REF_NOT_FOUND: Ref "docs/installation": "/MyBlog/Main/content/s/_index.zh-cn.md:15:113": page not found
ERROR [zh-cn] REF_NOT_FOUND: Ref "samples": "/MyBlog/Main/content/s/_index.zh-cn.md:15:176": page not found
Built in 125 ms
Error: error building site: logged 2 error(s)
我们只需要按照报错的目录和行数，将对应的错误修正即可。
值得注意的是，本地建立的网站会随着我们修改源文件而实时变化，所以我们在更改配置或编写文章时，可以实时查看呈现出的效果，十分方便。
10.创建文章#
在 hugo 中创建文章，可以输入：
hugo new xxx.md
这会创建一个 xxx.md 文件，且这个文件会以 archetypes 文件夹中的 default.md 作为模板。因此我们可以先修改 archetypes ，这样以后就不用一一添加了。
然而，我更推荐手动创建文件夹，再在文件夹中创建文档，具体可以看 这里 。
我们的文章通常都保存在 content 文件夹中，但如果直接在 content 目录下创建文章，会杂乱无章难以找到。因此，我们可以创建一些文件夹，作为文档库，每个文档库下存放不同的文章，这样就很方便了。（这些文档库就对应了 menus.zh-cn.toml 中的 pageRef ）
对于单独的文章，我们可以先建立一个文件夹，名称内只包括英文和下划线。然后在文件夹中建立 index.md ，这样每篇文章互不影响。在每篇文章的文件夹内，可以放置一个 feature 开头的图片文件，这样就可以设置该文章的缩略图。同时，也可以将文章中的图片放在文件夹内，便于索引。如图：
对 git 基础操作不了解的同学还是可以先看这篇文章：
首先将本地 git 连接到 github 的后端库上，并设置名称为 origin ，接下来将本地库 push 到后端库上。在网站根目录下输入（第二行后面改成你自己的后端库 SSH 地址）：
git init -b main
git remote add origin git@github.com:DeathGarurumon/HouDuan.git
git pull --rebase origin main
git add .
git commit -m "first commit"
git push origin main
之后，刷新一下网页，就能发现后端库中出现了你的源码。
转到前端库，点击 Actions ，些许等待后，会发现后端库的 /public 文件夹已经push 进来了，而且成功 deploy。
此时我们访问 https://deathgarurumon.github.io/ ，就可以看到我们的博客啦！
后记#
之后的博客生涯中，我们只需要修改本地文件，hugo server 查看效果，然后 git 三连，即可更新我们的博客。git 三连如下：
git add .
git commit -m "xxx"
git push origin main