使用 Hugo 对博客的重建与 Stack 主题优化记录

为何再次重建博客？

是，我知道我上次更新博客是2021年，但是这个博客我的确是没有忘的。（主播只是入狱了）

实际上这个博客是我在21年暑假用Hugo建的，使用的是Eureka主题。整体效果确实非常不错，但遗憾的是配置过程极其奇怪：虽说有专门的说明文档,但是于我而言这玩意写得实在是不太友好太坏了，准备写邮件去骂.jpg，所以当时我的配置过程纯粹靠蒙，虽说最后还是搞出来了，但确实是一种折磨。

正好最近几天又想写博客了，就把Hugo又下了回来，结果升级Eureka主题的时候又折磨了好久，还是没整明白。

使用git submodule下来的Eureka配置后存在的大量报错，不断提示module未定义，反正也看不懂，干脆换主题了。

因此本次的折腾就再走一遍之前的路，从零开始重建博客，顺带记录下以防之后忘记。

Hugo之安装

“Hugo是由Go语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。 ”

本次我使用的是 Hugo v0.111.2 与 git v2.38.0 ，操作系统为 win 11。在 Hugo 的releases和 Git 的官网都能很方便地下载。我选择的是 hugo_extended_0.111.2_windows-amd64.zip

版本，以便后续折腾。下载完成后将压缩包里的东西解压至你喜欢的目录，再将该目录的路径添加到环境变量中以便后续调用。至于 Git 的安装，我就不再赘述了。

Hugo建站

新建网站

运行 Hugo.exe 后，输入:

hugo new site ./path //比如我这里就是./exnadio.github.io

运行后便会输出一个网站目录，其结构为（引用自炸鸡人博客）：

1

2

3

4

5

6

7

8

.

├── archetypes # 存放文章模板

├── config.toml # 简单的配置文件

├── content # 存放文章

├── data # 存放生成静态页面时的配置文件

├── layouts # 存放页面布局的模板

├── static # 存放图片等静态内容

└── themes # 存放下载的主题

此时便搭好了一个基础框架，可以进行主题的导入了。

导入主题

这一步你就可以打开 Hugo Themes 这个网站，选择一个你喜欢的主题，然后跟随着它的说明一步一步配置就大功告成了。那么我们下期再见

实际上我认为这步是整个 Hugo 建站中最复杂的一步。且每个人选择的主题不尽相同，很难以一个完善的教程（何况我这篇是否算教程也有待考虑）通杀一切，我就分享下我这次的经历好了。

安装主题一般而言存在三种方式：

git submodule 安装

go module 安装（需要安装 Go 语言）

本地安装

我个人更推荐第一种方式，考虑到后续升级的难易，这算是最均衡的一种方式。具体的安装方法可以在各主题的说明中找到，我这里安装的是Stack。

在网站目录下，输入：

1

2

git init

git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

等待下载完成后，便可以进行配置了。假如你想用其他方式安装，也可以参考这里。

Stack本身有全英文的说明文档，我建议是将./themes/hugo-theme-stack/exampleSite/content和./themes/hugo-theme-stack/config.yaml直接夺舍，根据说明与需求修改，会剩下很多时间。

根据 Stack 的说明文档，Stack后续将改用.toml格式的Config文件，不过其配置步骤基本相同。

预览网站

很多教程会先教创建文章，不过我觉得配置完主题后还是先预览网站为好。Hugo的一大好处就是可以进行即时预览，你可以看到你每一步修改所产生的变化，也可以看到你是如何把一切搞崩溃的。

输入:

1

hugo server

即可建立一个本地服务器。

当然你也可以加上一些 flag 来达到一些其他目的：比如指定主题的--theme=Stack和关闭快速渲染的--disableFastRender等，具体可以查阅文档。

之后便可以在浏览器里打开http://localhost:1313预览。

创建文章

Hugo中的文章采用Markdown格式，通过以下命令你可以在./content/post路径下创建一篇文章：

hugo new post/rebuild_blog.md

打开后你会发现生成的Markdown文档带有一段FrontMatter部分，具体的意思可以在这里找到。大体上可以认为是文档的一些属性。

虽然大部分的主题都会帮你配置好 FrontMatter 部分，但是也是有部分主题是需要自行配置的，很不幸，Stack 就是这类主题之一。不过这也没啥关系，修改之前提到的./archetypes/default.md/下的default.md即可。

生成静态页面

只需输入：

1

hugo

即可。默认生成位置为./public，你可以在配置文档中使用publishDir参数指定，也可以直接使用-d参数指定。

发布网站

首先，我不会 git。

其次，本部分全文抄袭自炸鸡人博客。

这里用 Github Pages 来部署博客。首先在config.yaml里指定:

publishDir: docs

然后再一个hugo命令，这样就把静态页面输出到docs目录下了。

接着在 Github 上以 ZhaJiMan.github.io 的名字（根据自己的用户名而定）新建一>个空仓库，进行下面的 Git 命令:

git add .

git commit -m “first commit”

git branch -M main

git remote add origin https://github.com/ZhaJiMan/ZhaJiMan.github.io.git

git push -u origin main

这段改编自空仓库页面出现的提示，大意是:

将网站目录下的所有内容暂存。

把暂存的内容提交给版本库。

把主分支的名字从 master 改为 main。

添加远程仓库。

把本地内容推送到远程仓库里。

推送成功后，进入仓库的设置页面，点击侧栏的 Pages，再把 Source 选项改为 main 分支下的docs目录，这样 Github Pages 就会根据我们推送上去的docs目录里的静态页面来显示网站。这里指定docs的好处是还可以把网站的所有文件都备份到仓库里（不包含以 submodule 形式添加主题，详见参考链接）。最后在与仓库同名的网站 https://zhajiman.github.io/ 上看看自己的博客吧！

我补充几个细节：

git push -u origin master //我采用了master分支后是要验证github账号的（也许只有首次有？），假如你没有，那么我建议你读第2点。

Github是有带GUI的客户端的，git苦手可以考虑用这个。

主题配置历程

由于主题的配置是个个体差异极大的过程，因此我不会事无巨细地说明每一个过程，而是说明几个小点。

网站图标更改

其实很简单，但是我被一个issue误导了，哈哈。

将图片生成的favicon文件夹放在./static文件夹下，然后在cofig.yaml下指定：favicon: /favicon/favicon.ico 就行。

评论系统之接入

忘了Uttrances怎么配置的了啊嗯，鸽了。

已将评论系统改为giscus，配置过程见这里

Stack主题自定义

首先放一下对比图：

改善浅色模式可读性

配置完 Stack 后，我并不是很满意，假如说满分100的话我只能打个70分左右。最大的不满在于其浅色模式下可读性实在是过于糟糕,你可以在 Demo网站 上感受一下，我不清楚为什么作者采用了#bababa这个颜色，导致其与背景的对比度来到了可怜的1.94，简直就是一场彻头彻尾的灾难。

不过好在 Stack 主题预留了自定义的空间，详见官网的说明。这里具体介绍下自定义的方法：

在Stack以及很多主题中，主题文件夹下的assets/scss下都提供了一个供用户自定义的custom.scss文件。

原理便是在最后引入这个文件，使其位于最终css文件的末尾，从而覆盖原先的属性，达到“自定义”的效果。

因此，想要自定义就很简单了：找到你希望修改的元素和它对应的选择器，重新定义这个选择器即可。

万幸，目前的浏览器为我们提供了好用的开发者工具。以我现在使用的Edge为例，按下F12弹出开发者工具，使用左上角的小箭头使你的鼠标变成一个查看器(你也可以使用SHIFT+CTRL+C的组合键)，只要将光标置于你想修改的元素上，就能找到该元素的源代码。

例如我现在想改浅色模式下的文本颜色，只需选择一段文本,就能在右下角找到它对应的css:

可以看到文本被指定为---body-text-color。

再顺藤摸瓜找到对应的颜色控制：

把要修改的部分直接复制出来放进custom.scss文件中，修改下即可。比如我使用的这套：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

:root {

--body-background: #EBEBEB;

--accent-color: #1B365D;

--accent-color-darker: #202A44;

--accent-color-text: #FFF;

--body-text-color: #202A44;

}

:root {

--card-background: #FFF;

--card-background-selected: #EBEBEB;

--card-text-color-main: #202A44;

--card-text-color-secondary: #53565A;

--card-text-color-tertiary: #888B8D;

}

此时就能达到这种效果了：

Tag的修改我也说下，用上面的方法找到代码，发现：

Is this LGBT light?

然后把能找到这些颜色的地方全图图了：

1

2

3

4

5

6

7

8

9

.article-list article:nth-child(n) .article-category a {

background: #1B365D;

color: #fff;

}

.article-category a, .article-tags a {

background-color: #1B365D;

color: #fff;

}

Note:

改完之后我发现分类的 Tag 还是存在问题，虽说前几个颜色是对的，但是越往后走居然开始变色了：

此时即使在custom.scss中指定了颜色也没啥用，看了下这玩意居然在是element.style写死的，多少有点幽默：

于是便需要在源代码后面加上!important，Done。

现代码如下：

1

2

3

4

5

6

7

8

9

.article-list article:nth-child(n) .article-category a {

background: #1B365D!important;

color: #fff;

}

.article-category a, .article-tags a {

background-color: #1B365D!important;

color: #fff;

}

修改网站布局

原先挤满所有空间的布局我不喜欢，遂改。

这里使用仙贝的代码，一样是在custom.scss中添加：

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

35

36

.container {

margin-left: auto;

margin-right: auto;

&.extended {

/* range: 768-1024 */

@include respond(md) {

max-width: 1024px;

--left-sidebar-max-width: 25%;

--right-sidebar-max-width: 30%;

}

/* range: 1024-1280 */

@include respond(lg) {

max-width: 1280px;

--left-sidebar-max-width: 25%;

--right-sidebar-max-width: 22%;

}

}

&.compact {

@include respond(md) {

--left-sidebar-max-width: 25%;

max-width: 768px;

}

@include respond(lg) {

max-width: 1024px;

--left-sidebar-max-width: 20%;

}

@include respond(xl) {

max-width: 1280px;

}

}

}

即可。

老头滚动条修改

同上，不喜欢，仙贝代码，添加：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

html{

::-webkit-scrollbar {

width: 20px;

}

::-webkit-scrollbar-track {

background-color: transparent;

}

::-webkit-scrollbar-thumb {

background-color: #d6dee1;

border-radius: 20px;

border: 6px solid transparent;

background-clip: content-box;

}

::-webkit-scrollbar-thumb:hover {

background-color: #a8bbbf;

}

}

图标添加与修改

Stack主题带了几个很好看的Tabler图标，可惜并不全，部分缺失的图标要手动添加。

例如我想添加一个比比汗丽丽的图标，在Tabler官网搜索发现居然真有：

将svg文件其下载到.\themes\hugo-theme-stack\assets\icons中，再调用即可。

另外，我也不是很喜欢自带的深色模式切换开关，以我个人的的观点来看，这玩意太不直观了：

图标的添加方式就不再赘述，我这里选的是"sun-high"和"moon-stars"这两个图标。

观察网页的CSS可以发现：深色模式下图标的切换就是“一个显示，一个隐藏”，在相关文件中指定该用的图标即可。

作者将这个开关做在了侧边栏里，因而直接在有关的.\assets\scss\partials\sidebar.scss和\layouts\partials\sidebar\left.html里指定图标即可:

``

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

/* .\assets\scss\partials\sidebar.scss Line 154*/

[data-scheme="dark"] {

#dark-mode-toggle {

color: var(--accent-color);

font-weight: 700;

.icon-tabler-sun-high {

display: none;

}

.icon-tabler-moon-stars {

display: unset;

}

}

}

#dark-mode-toggle {

margin-top: auto;

color: var(--body-text-color);

display: flex;

align-items: center;

cursor: pointer;

gap: var(--menu-icon-separation);

.icon-tabler-moon-stars {

display: none;

}

}

1

2

3

4

5

6

7

8

{{ if (default false .Site.Params.colorScheme.toggle) }}

{{ partial "helper/icon" "sun-high" }}

{{ partial "helper/icon" "moon-stars" }}

{{ T "darkMode" }}

{{ end }}

效果如下：

顺带一提，想改中文翻译直接去\i18n\zh-cn.yaml中修改即可（暗色模式这翻译也太怪了）。

添加字数统计

Stack本身是不带字数统计的，但是Hugo本身是支持进行字数统计的。所以我决定，写一段字数统计的代码。

Stack的文章页面是由三个html控制的：

1

2

3

4

.

├── details.html

├── content.html

└── footer.html

所以在details.html中加入相应的字数统计代码就行了。

在互联网上找了一圈后，我发现之前就有人写过相关代码。

1

2

3

4

5

6

7

{{ if .Site.Params.article.readingTime }}

然而这段代码没有多语言支持，所以我决定让事情变得更复杂：全面照抄Stack实现阅读时长的方式。

首先在congfig.yaml中的.params.article中添加：

1

wordCount: true

然后参考前面的和readTime的代码，在detail.html中加上下面的代码：

1

2

3

4

5

6

7

8

{{ if .Site.Params.article.readingTime }}

{{ end }}

之后只要添加多语言支持，也就是在i18n文件夹中修改对应语言的.yaml文件就好了。以英文为例，在.\i18n\en.yaml中加上：

1

2

wordCount:

other: "{{.Count}} words"

便完事大成了。反正一切主打的就是一个readTime在哪我在哪

顺带改了下图标，参考这里

文章修改时间显示

修改时间就没有字数统计这么麻烦了。Stack本身自带修改时间显示，不过这玩意放在了最底下，不太直观，我就把它提上来了。

源代码看位置就在.\layouts\partials\article\components\footer.html里，果不其然：

1

2

3

4

5

6

7

8

{{- if ne .Lastmod .Date -}}

{{ partial "helper/icon" "clock" }}

{{ T "article.lastUpdatedOn" }} {{ .Lastmod.Format ( or .Site.Params.dateFormat.lastUpdated "Jan 02, 2006 15:04 MST" ) }}

{{- end -}}

前面也说了，日期、阅读时间之类被放在了.\layouts\partials\article\components\footer.html里，因此在参考日期的代码和源代码基础上做点修改，添加进去就行：

1

2

3

4

5

6

7

8

{{- if ne .Lastmod .Date -}}

{{ end }}

顺带，为了自动更改修改时间，在config.yaml中添加：

1

2

frontmatter:

lastmod: [":fileModTime", "lastmod"]

友情链接改为双列显示

这里我用的是大佬的代码，修改过程和之前一样，在custom.scss添上以下css即可：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

@media (min-width: 1024px) {

.article-list--compact.links {

display: grid;

grid-template-columns: 1fr 1fr;

background: none;

box-shadow: none;

article {

background: var(--card-background);

border: none;

box-shadow: var(--shadow-l2);

margin-bottom: 8px;

border-radius: 10px;

&:nth-child(odd) {

margin-right: 8px;

}

}

}

}

目前仍未完成的部分

当然目前这个网站仍存在以下问题以及遗憾：

过往文章未恢复

评论系统未接入

部分界面还未配置好

网站图标未设置（其实是还没做）

没有文章修改时间显示

洋文站点还没完成

Category机制还没搞懂 他妈的，实在搞不懂。 Fuck,that’s a feature.

以上，下次大概的确会修复！

预告部分

主题配置历程

Markdown小教程

つづく

参考链接

用 Hugo 重新搭建博客

Hugo Stack主题更新小记

将Hugo Stack主题友情链接改为双列显示

Hugo | 看中 Stack 主题的归档功能，搬家并做修改

Page Variables