Hugo 主题 - Stack

简介

Stack 是一款简约、优雅、响应式的 Hugo 主题，卡片式设计，适用于个人博客、技术文档等。本博客用的就是它。

主题文档：https://stack.cai.im/zh
GitHub 开源仓库地址：https://github.com/CaiJimmy/hugo-theme-stack
在线演示：https://demo.stack.cai.im

页面整体布局大概是这样的：

Stack 主题页面布局

特性

No CSS and JavaScript framework
不依赖任何 CSS / JavaScript 框架，保持网站轻量、快速。样式用 SCSS 编写，脚本用原生 TypeScript 编写，由 Hugo 自己编译。

简约、优雅、响应式，手机上左侧栏会收起为菜单；
支持 Dark Mode，可以跟随系统，也可以手动切换；
支持多语言，内置 30 多种界面语言；
支持代码高亮，代码块带一键复制按钮；
支持评论系统：Disqus、DisqusJS、giscus、utterances、Gitalk、Waline、Twikoo、Artalk、Remark42、Cusdis、Vssue、Cactus、Beaudar、Comentario；
支持文章目录（TOC），阅读时自动高亮当前章节；
支持本地全文搜索、归档页、分类和标签；
支持 KaTeX 数学公式、Mermaid 图表；
支持 GitHub 风格的提示块（> [!NOTE] 等）；
支持图片画廊（PhotoSwipe）、图片自动缩放裁剪；
支持 Open Graph、Twitter Card 等社交分享元数据；
内置 Bilibili、YouTube、腾讯视频、本地视频、GitLab Snippet、引用等短代码。

安装

Stack v4 推荐以 Hugo Module 的方式引入，不需要把主题源码复制进仓库，也不用 Git Submodule。

环境要求

Hugo extended 版，v4 要求 0.157.0 及以上；
Go（Hugo Module 依赖 Go 来拉取模块）；
Git。

1
2
hugo version   # 确认带 +extended
go version

引入主题

最省事的办法是直接用官方的 hugo-theme-stack-starter 模板新建仓库。如果是已有站点，手动做三步：

把站点初始化为一个 Hugo Module（模块路径一般写仓库地址）：
1
hugo mod init github.com/<你的用户名>/<仓库名>
在配置中导入主题。本博客把配置拆分在 config/_default/ 下，主题导入写在 module.toml：
1 2
[[imports]] path = "github.com/CaiJimmy/hugo-theme-stack/v4"

拉取主题：

1
hugo mod get github.com/CaiJimmy/hugo-theme-stack/v4

完成后，go.mod 里会多出一行依赖，锁定了主题版本：

1
2
3
4
5
6
7
module github.com/1orz/hugo-blog

go 1.25

require (
	github.com/CaiJimmy/hugo-theme-stack/v4 v4.0.3 // indirect
)

整个引入过程如下：

Hugo Module 引入主题的过程

升级主题

1
2
3
4
5
# 升级到最新版本
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v4

# 整理 go.mod / go.sum
hugo mod tidy

主题版本记录在 go.mod 中，升级前后都可以对比；从 v3 升级到 v4 这种大版本时，模块路径带 /v4 后缀，需要同时修改 module.toml 里的 path，并对照主题文档检查配置项的变化。

配置

配置文件结构

Hugo 支持把配置拆成多个文件放在 config/_default/ 下，文件名就是顶层键名，比一个巨大的 hugo.toml 好维护得多：

1
2
3
4
5
6
7
8
9
config/_default/
├── config.toml      # baseURL、语言、标题等站点基础配置
├── languages.toml   # 多语言
├── markup.toml      # Markdown 渲染、代码高亮
├── menu.toml        # 社交链接菜单
├── module.toml      # 导入主题
├── params.toml      # 主题参数
├── permalinks.toml  # 文章链接格式
└── related.toml     # 相关文章

常用主题参数

以下都写在 params.toml 中，键名以主题自带的 config/_default/params.toml 为准：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
mainSections = ["post"]   # 首页和归档页展示哪个目录下的文章

[sidebar]
avatar = "img/avatar.jpg" # 头像，放在 assets/img/ 下
subtitle = "一句话介绍"

[article]
toc = true                # 文章目录
readingTime = true        # 阅读时间
math = false              # 全局开启 KaTeX，也可以在单篇文章里开

[colorScheme]
toggle = true             # 显示明暗切换按钮
default = "auto"          # auto / light / dark

[comments]
enabled = true
provider = "giscus"       # 评论系统，具体参数写在 [comments.giscus] 等小节里

小组件

首页右侧和文章页右侧的小组件分别由 widgets.homepage 和 widgets.page 控制，可选 search、archives、categories、tag-cloud、toc：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[[widgets.homepage]]
type = "search"

[[widgets.homepage]]
type = "archives"
[widgets.homepage.params]
limit = 5

[[widgets.homepage]]
type = "tag-cloud"
[widgets.homepage.params]
limit = 10

[[widgets.page]]
type = "toc"

搜索页和归档页

这两个页面需要自己新建，指定对应的 layout 即可，例如 content/page/search/index.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
---
title: "搜索"
slug: "search"
layout: "search"
outputs:
    - html
    - json
menu:
    main:
        weight: -60
        params:
            icon: search
---

归档页同理，layout 写 archives。

写文章

主题常用的 front matter 字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
---
title: "文章标题"
description: "显示在标题下方的简介"
slug: "url-slug"
date: 2024-04-19T13:14:05+08:00
image: cover.jpg       # 封面图，与 index.md 放在同一目录
math: true             # 单篇开启 KaTeX
license: false         # 单篇关闭版权声明
comments: true         # 单篇开关评论
categories: ["Hugo"]
tags: ["Hugo"]
---

插入 B 站视频、引用等可以用内置短代码，例如：

1
2
3
4
5
{{< bilibili BV1xx411c7mD >}}

{{< quote author="作者" source="出处" >}}
引用的内容
{{< /quote >}}

自定义

不需要改主题源码。Hugo 的查找顺序是“站点目录优先，主题其次”，在站点里放同路径的文件就能覆盖主题：

layouts/_partials/head/custom.html：往 <head> 里加统计代码、自定义样式等；
layouts/_partials/footer/custom.html：往页面底部加脚本；
assets/scss/custom.scss：覆盖样式变量或追加样式。

这样升级主题时，自定义内容不会被覆盖。