Hugo Stack 主题详细配置及使用指南
你想要全面掌握 Hugo Stack 主题的配置与使用，我会从环境准备、主题部署、核心配置、内容创作到高级自定义，为你提供完整的操作流程。
一、前置准备
1. 安装 Hugo
Stack 主题对 Hugo 版本有要求（推荐 Hugo Extended 0.91.0+，必须是 Extended 扩展版本，用于支持 SCSS 样式编译）：
- Windows：通过 Chocolatey 安装
choco install hugo-extended，或直接从 Hugo 官网 下载二进制文件
- Mac：通过 Homebrew 安装
brew install hugo
- Linux：通过包管理器安装（如 Ubuntu：
sudo apt install hugo-extended）
- 验证安装：
hugo version，输出包含 extended 字样即为成功
2. 新建 Hugo 站点
打开终端执行以下命令，创建基础站点目录：
1
2
3
4
5
6
|
# 创建站点目录（替换 my-blog 为你的站点名称）
hugo new site my-blog
# 进入站点目录
cd my-blog
# 初始化 Git 仓库（后续主题部署需要）
git init
|
二、安装 Stack 主题
推荐使用 Git Submodule 方式安装（方便后续主题更新），也支持手动下载安装。
方式 1：Git Submodule 安装（推荐）
1
2
|
# 在站点根目录执行，将 Stack 主题作为子模块导入
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack
|
方式 2：手动下载安装
- 从 Stack 主题 GitHub 仓库 下载最新版本（Code -> Download ZIP）
- 解压压缩包，将文件夹重命名为
stack，放入站点的 themes/ 目录下（若没有 themes 文件夹，手动创建）
三、基础配置（核心：config.toml）
站点的核心配置文件是根目录下的 config.toml，需替换默认内容，以下是 Stack 主题的基础配置模板，关键配置已标注说明：
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
# 站点基础信息
baseURL = "https://your-domain.com/" # 你的站点域名（本地调试可设为 "http://localhost:1313/"）
languageCode = "zh-cn" # 站点语言（中文设为 zh-cn）
title = "我的博客" # 站点标题
theme = "stack" # 指定使用 Stack 主题
defaultContentLanguage = "zh-cn"
enableInlineShortcodes = true
enableRobotsTXT = true # 启用 robots.txt
# 分页配置
paginate = 10 # 首页/分类页每页显示文章数量
# Stack 主题专属配置 [params]
[params]
# 站点描述（用于 SEO）
description = "一个基于 Hugo Stack 主题搭建的个人博客"
# 作者信息
author = "你的名字"
# 站点关键词（逗号分隔）
keywords = ["博客", "技术", "Hugo", "Stack"]
# 外观配置
defaultTheme = "light" # 默认主题（light/ dark/ auto）
displayFullLangName = true # 显示完整语言名称
imageProcessing = true # 启用图片处理（压缩、裁剪等）
# 导航栏配置（顶部菜单）
[params.menu]
main = [
{ identifier = "home", name = "首页", url = "/", weight = 1 },
{ identifier = "posts", name = "文章", url = "/posts/", weight = 2 },
{ identifier = "categories", name = "分类", url = "/categories/", weight = 3 },
{ identifier = "tags", name = "标签", url = "/tags/", weight = 4 },
{ identifier = "about", name = "关于", url = "/about/", weight = 5 },
]
# 页脚配置
[params.footer]
enable = true
text = "© 2026 我的博客 | 基于 Hugo & Stack 构建"
# 社交图标（支持 Github、Twitter 等，完整列表参考 Stack 文档）
social = [
{ name = "Github", url = "https://github.com/your-username" },
{ name = "Email", url = "mailto:your-email@xxx.com" }
]
# 内容类型配置（Stack 主题推荐）
[taxonomies]
category = "categories"
tag = "tags"
series = "series"
# Markdown 配置
[markup]
defaultMarkdownHandler = "goldmark"
[markup.goldmark]
[markup.goldmark.extensions]
definitionList = true
footnote = true
linkify = true
strikethrough = true
table = true
taskList = true
typographer = true
# 启用代码高亮
[markup.highlight]
codeFences = true
lineNos = false
lineNumbersInTable = false
noClasses = false
|
四、内容创作
1. 新建文章
使用 Hugo 命令快速创建文章，自动生成 Front Matter（文章头部配置）：
1
2
|
# 新建一篇标题为 "Hugo Stack 主题使用教程" 的文章
hugo new posts/hugo-stack-guide.md
|
2. 文章 Front Matter 配置（关键）
新建的文章位于 content/posts/ 目录下，打开后需完善 Front Matter（YAML 格式，也支持 TOML/JSON），以下是完整示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
---
title: "Hugo Stack 主题使用教程" # 文章标题
date: 2026-01-04T10:00:00+08:00 # 发布时间
lastmod: 2026-01-04T15:00:00+08:00 # 最后修改时间
draft: false # 是否为草稿（false 为正式发布）
tags: ["Hugo", "Stack", "博客搭建"] # 文章标签
categories: ["技术教程"] # 文章分类
series: ["Hugo 实战"] # 文章系列（可选）
featuredImage: "cover.jpg" # 文章特色图片（放在 static/images/ 下，路径写相对路径）
featuredImagePreview: "cover-preview.jpg" # 特色图片预览（可选）
toc: true # 是否显示目录
tocOpen: true # 是否默认展开目录
summary: "本文详细介绍 Hugo Stack 主题的配置与使用方法" # 文章摘要
---
# 这里开始写文章正文（支持 Markdown 格式）
## 一、什么是 Hugo Stack 主题
Stack 是一款简约、美观、高性能的 Hugo 主题，专注于内容展示，支持响应式布局。
// 正文内容...
|
3. 新建独立页面（如关于页）
1
2
|
# 新建关于页
hugo new about.md
|
打开 content/about.md，完善内容即可，Front Matter 配置可简化：
1
2
3
4
5
6
|
---
title: "关于我"
date: 2026-01-04T09:00:00+08:00
draft: false
---
这里是关于我的介绍内容...
|
4. 图片管理
- 文章内图片推荐放在
static/images/ 目录下，在文章中引用：
- 特色图片（featuredImage）直接填写
/images/xxx.jpg 即可，Stack 主题会自动处理图片尺寸
五、本地调试与预览
在站点根目录执行以下命令，启动本地服务器：
1
2
|
# 启动本地调试服务器，支持热重载（修改配置/文章后自动刷新）
hugo server
|
执行成功后，访问 http://localhost:1313/ 即可预览你的博客站点。
六、生成静态站点（部署前准备）
本地调试无误后，执行以下命令生成静态 HTML 文件（用于部署到服务器/Netlify/GitHub Pages 等）：
1
2
|
# 生成静态站点，输出到 public/ 目录
hugo
|
生成完成后，public/ 目录下的所有文件即为可部署的静态站点资源。
七、高级自定义
1. 自定义样式
无需修改主题源码，在站点根目录创建 assets/scss/custom.scss 文件，写入自定义 CSS/SCSS 样式，示例：
1
2
3
4
5
6
7
8
9
10
|
// 自定义首页文章卡片样式
.card {
border-radius: 8px;
box-shadow: 0 2px 10px rgba(0,0,0,0.05);
}
// 自定义标题颜色
h1, h2, h3 {
color: #2c3e50;
}
|
2. 自定义首页布局
Stack 主题支持两种首页布局：
- 列表布局（默认）：显示文章列表
- 封面布局：显示一张大封面图 + 站点简介
修改 config.toml 启用封面布局：
1
2
3
4
5
6
7
8
9
10
11
|
[params]
# 首页封面布局配置
[params.home]
layout = "cover" # 切换为封面布局（list 为默认列表布局）
[params.home.cover]
enable = true
image = "/images/cover.jpg" # 封面图片路径
title = "我的个人博客"
subtitle = "专注技术分享与生活记录"
# 是否显示文章列表（封面下方）
displayPosts = true
|
3. 启用评论功能（以 Giscus 为例）
Stack 主题原生支持 Giscus、Disqus 等评论系统，以 Giscus 为例（基于 GitHub Discussions）：
- 先在 Giscus 官网 完成配置，获取对应的
repo、repoId、categoryId 等参数
- 在
config.toml 中添加以下配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
[params]
[params.comments]
enable = true
# 选择评论系统为 giscus
type = "giscus"
[params.comments.giscus]
repo = "your-username/your-repo" # 你的 GitHub 仓库（格式：用户名/仓库名）
repoId = "你的 repoId"
category = "Announcements" # 仓库的 Discussions 分类
categoryId = "你的 categoryId"
mapping = "pathname"
reactionsEnabled = "1"
emitMetadata = "0"
lang = "zh-CN"
theme = "light"
|
4. 启用搜索功能
Stack 主题支持本地搜索（基于 Fuse.js），配置如下：
1
2
3
4
5
6
7
|
[params]
[params.search]
enable = true
type = "local" # 本地搜索（也支持 algolia 第三方搜索）
[params.search.local]
preload = true
fuse = { threshold = 0.3 }
|
八、主题更新
若使用 Git Submodule 安装的主题，可通过以下命令更新到最新版本：
1
2
3
4
5
6
7
8
9
|
# 进入主题目录
cd themes/stack
# 拉取最新代码
git pull origin master
# 返回站点根目录
cd ../../
# 提交更新记录（可选）
git add themes/stack
git commit -m "更新 Stack 主题到最新版本"
|
九、部署建议
- GitHub Pages：将
public/ 目录的内容推送到 username.github.io 仓库的 main 分支（可配合 GitHub Actions 自动部署）
- Netlify/Vercel：直接导入你的 Hugo 站点仓库，配置构建命令
hugo，输出目录 public，自动完成部署
- 自建服务器：将
public/ 目录上传到 Nginx/Apache 服务器的网站根目录即可
总结
- 核心前提：安装 Hugo Extended 版本，通过 Git Submodule 安装 Stack 主题更易维护
- 基础配置：重点完善
config.toml 的 [params] 节点（导航、页脚、外观等）
- 内容创作：通过
hugo new 命令创建文章，完善 Front Matter 是关键
- 本地调试：
hugo server 热重载预览，hugo 生成静态站点
- 高级自定义：支持自定义样式、首页布局、评论/搜索功能，无需修改主题源码
- 部署：
public/ 目录为最终静态资源，可部署到 GitHub Pages/Netlify 等平台