本文已同步发表在使用 Hugo 和 GitHub Pages 搭建并部署一个静态博客网站 | Jared Yam
最近打算将我在 CSDN 上发布并持续优化的部分内容同步至 GitHub,这些内容十分需要借助 Git 记录和追溯修改历史,而 GitHub 也可以作为这些内容的另一个获取平台。
将文档直接丢进 GitHub 仓库好像又差点意思。GitHub Pages 为每个 GitHub 账户免费提供一项静态网站托管服务,通过域名 https://
本文将介绍如何使用 Hugo 搭建静态博客网站、使用和定制 hugo-PaperMod 主题以及将网站部署在 GitHub Pages。
如今搭建静态网站的方法已经非常成熟,我根据网友讨论和个人喜好选择 Hugo 作为静态网站搭建框架,同样流行的框架还包括 Hexo、Jekyll 等。
Hugo 提供多种操作系统的安装指引。以我的 macOS 系统为例,可以通过包管理器 brew
快速完成安装:
brew install hugo
使用 Hugo 可以快速创建一个网站模板:
brew new site <your-github-id>.github.io -f yml
其中
对应新建网站的项目文件夹(
需替换为 GitHub ID),选项 -f
将网站配置文件设置为 YAML
格式,其目的是为与下文主题配置保持一致。为方便起见,下文将网站项目文件夹简称为「网站」。
在流行框架的基础上搭建网站其实并不是一个技术活,千差万别的网站体验则主要体现在网站主题的设计上。Hugo 提供丰富多样的主题模板,我根据网友讨论选择 adityatelange/hugo-PaperMod 作为基础主题。PaperMod 页面简洁,支持暗黑模式及众多实用特性。
在网站根目录执行以下命令下载主题并初始化为 Git 子模块:
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
git init
git submodule--helper add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod --depth=1
随后,我们只需将主题名称写入配置文件 ./config.yml
:
baseURL: https://jaredyam.github.io
languageCode: en-us
defaultContentLanguage: zh
title: Jared Yam
# 主题
theme: PaperMod
便搭建完成了一个完整的静态博客网站。
执行以下命令可以在本地预览网站:
hugo server -D
其中选项 -D
允许在预览网站时渲染未发布的草稿文档。同时,我们还可以尝试新建一个文档:
hugo new posts/quickstart.md
刷新并点击进入该文档对应的网页视图。
除此之外,你还可以跟随主题配置指引,根据个人喜好调整主题基础设置,添加或取消部分功能。如果你没有其它定制主题的需求,可直接跳过下一节内容。
定制主题除了修改配置文件,还可以重写模板和风格。接下来介绍的个性化配置可能持续更新,且细节部分不做赘述。如果你对我的网站主题配置感兴趣,可以随时查看其对应的仓库源文件。
❓ 如何查看我在基础主题上做过哪些调整?
git clone https://github.com/jaredyam/jaredyam.github.io.git cat ./config.yml diff -ur themes/PaperMod/assets assets diff -ur themes/PaperMod/layouts layouts
Pull Request #675 · adityatelange/hugo-PaperMod 提出将文章目录转移至侧边栏,可以轻松实现上下文跳转。截至发文这一特性还未并入主分支,我们可以让主题子模块追踪该远程 PR 分支:
cd themes/PaperMod
git fetch origin pull/675/head:toc-on-the-side --depth=1
git checkout toc-on-the-side
cd ../..
除了切换到 PR 分支,我们还需要让子模块配置文件 ./gitmodules
指向 PR 分支:
[submodule "themes/PaperMod"]
path = "themes/PaperMod"
url = "https://github.com/nielsbrakel/hugo-PaperMod.git"
branch = "toc-on-the-side"
然后再同步子模块 URL 到 .git/config
:
git submodule sync
基础主题默认不显示目录栏,我们需要在主题配置文件 ./config.yml
中启用并展开目录:
baseURL: https://jaredyam.github.io
languageCode: en-us
defaultContentLanguage: zh
title: Jared Yam
# 主题
theme: PaperMod
params:
# 目录
ShowToc: true
TocOpen: true
值得注意的是,远程 PR 分支可能并不涵盖主分支的最新特性。你可以通过创建一个 fork 仓库同时追踪主分支和 PR 分支的更新。
giscus 是一个基于 GitHub Discussions 的评论系统,包含多种主题可供选择。你应该首先跟随 utterances 配置方法了解可选配置项,并根据个人偏好自动生成一份包含个性化配置属性的 HTML
代码:
<script src="https://giscus.app/client.js"
data-repo="jaredyam/jaredyam.github.io"
data-repo-id="R_kgDOG9Gq_Q"
data-category="Announcements"
data-category-id="DIC_kwDOG9Gq_c4CO_p0"
data-mapping="title"
data-reactions-enabled="1"
data-emit-metadata="1"
data-input-position="top"
data-theme="light"
data-lang="zh-CN"
crossorigin="anonymous"
async>
script>
官方提供的自动生成代码仅支持设置一个固定主题,而我们希望网站主题和评论系统主题的亮暗模式可以保持一致。参照 utterances 讨论系统主题切换的相关讨论,上述代码可以简单替换为:
<div class="comments">
<script>
function loadComment() {
let theme = localStorage.getItem('pref-theme') === 'dark' ? 'dark' : 'light';
let s = document.createElement('script');
s.src = 'https://giscus.app/client.js';
s.setAttribute('data-repo', '{{- site.Params.commentsParams.repo -}}');
s.setAttribute('data-repo-id', '{{- site.Params.commentsParams.repoId -}}');
s.setAttribute('data-category', '{{- site.Params.commentsParams.category -}}');
s.setAttribute('data-category-id', '{{- site.Params.commentsParams.categoryId -}}');
s.setAttribute('data-mapping', '{{- site.Params.commentsParams.mapping -}}');
s.setAttribute('data-reactions-enabled', '{{- site.Params.commentsParams.reactionsEnabled -}}');
s.setAttribute('data-emit-metadata', '{{- site.Params.commentsParams.emitMetadata -}}');
s.setAttribute('data-input-position', '{{- site.Params.commentsParams.inputPosition -}}');
s.setAttribute('data-lang', '{{- site.Params.commentsParams.lang -}}');
s.setAttribute('data-theme', theme);
s.setAttribute('crossorigin', 'anonymous');
s.setAttribute('async', '');
document.querySelector('div.comments').innerHTML = '';
document.querySelector('div.comments').appendChild(s);
}
loadComment();
script>
div>
从而根据当前网站主题设置讨论系统主题。将修改后的代码写入 ./layouts/partials/comments.html
即可在博客页面插入讨论系统。
不难看出,我们还需要在主题配置文件 ./config.yml
中设置一些评论系统参数才能使讨论系统正常加载:
baseURL: https://jaredyam.github.io
languageCode: en-us
defaultContentLanguage: zh
title: Jared Yam
# 主题
theme: PaperMod
params:
# 目录
ShowToc: true
TocOpen: true
# 评论系统
comments: true
commentsParams:
repo: jaredyam/jaredyam.github.io
repoId: R_kgDOG9Gq_Q
category: Announcements
categoryId: DIC_kwDOG9Gq_c4CO_p0
mapping: title
reactionsEnabled: 1
emitMetadata: 1
inputPosition: top
lang: zh-CN
其中 commentsParams
的子属性值应当与 giscus 自动生成的代码内容保持一致。
在手动切换网站主题亮暗模式时,评论系统主题应该随网站主题发生变化。在 ./layouts/partials/footer.html:72
区域加入如下代码块:
{{- if (not site.Params.disableThemeToggle) }}
{{- end }}
即可实现这一目的。
Hugo 提供非常详尽的 GitHub Pages 部署指引。这里对部署过程做简单梳理:
./.github/workflows/
中放入 gh-pages.yml;Settings -> Pages
中选择 gh-pages
作为网站资源分支。完成以上步骤,你便可以通过 https://