前言
本文为 Hugo Theme Stack 主题搭建教程（为Windows教程 Mac/Linux系统命令可能有所出入）
前置要求
本地已正确安装 Git、Hugo 环境，并配置好系统环境变量，可在终端正常调用相关指令。
1.初始化git
进入博客项目根文件夹，打开终端执行以下命令，初始化本地 Git 仓库 （可选：并配置远程仓库地址 如GitHub GitLab Gitea等）
1
|
git remote add origin 远程仓库地址（可选）
|
2.初始化hugo
使用hugo 创建hugo站点骨架 –force 意思为强制覆盖（因为git init 使该文件夹不为空 所以需要强制覆盖）
1
|
hugo new site . --force
|
3.下载主题
推荐使用 Git 子模块（submodule） 安装主题，区别于 git clone：该方式不会把主题代码提交进博客仓库 只会在根目录生成轻量标记 .gitmodules 文件：记录主题仓库地址、存放路径；目录记录：只保存当前锁定的主题提交哈希值（相当于记一个版本快照）；你的博客仓库永远干净，只有你自己写的文章、配置，第三方主题代码不入库。后期初始化并拉取子模块主题代码
3.1 添加主题子模块
根据自身网络环境选择对应命令（网络不稳定优先选择 SSH 方式）
1
2
|
# HTTPS 方式（通用，无需配置SSH密钥）
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
|
1
2
|
# SSH 方式（网络更稳定，需提前配置GitHub SSH密钥）
git submodule add git@github.com:CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
|
3.2 拉取主题完整源码
初始化并同步子模块，拉取 Stack 主题完整源码至 themes/hugo-theme-stack 目录
1
|
git submodule update --init --recursive
|
3.3 备用方案（网络卡顿适用）
如果拉取速度过慢 你也可以从 Stack 主题的 GitHub 页面下载 ZIP 压缩包，解压后将文件夹重命名为 hugo-theme-stack，并手动移动到 themes 文件夹内
4.应用配置主题
Stack 主题自带完整演示案例，直接复制演示配置和示例页面，可大幅减少手动配置成本，快速搭建成型博客
1
2
|
#复制配置目录
xcopy themes\hugo-theme-stack\demo\config config\ /E /I /Y
|
1
2
|
#复制示例页面（如关于、归档页等）
xcopy themes\hugo-theme-stack\demo\content content\ /E /I /Y
|
5.核心配置文件修改（关键步骤）
这是最关键的一步，我们将 Stack 主题的演示配置应用到你的站点，并修改基础信息
5.1 前置配置
你需要修改或确认以下关键项：
- 用文本编辑器（如 VS Code）打开 config/_default/hugo.toml。
- 指定主题：在文件顶部附近添加或找到 theme 行，确保其值为 hugo-theme-stack
- Hugo 初始化时可能在根目录生成了一个 hugo.toml 文件，它会和 config/_default/ 目录冲突。请手动删除它
5.2 配置文件参考
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
71
72
73
74
|
# ========================
# 基本站点设置
# ========================
# 站点的基础URL
# 本地预览时设为 "/"，部署到 GitHub Pages 时改为真实域名
# 例如：https://你的用户名.github.io/
baseURL = "/"
# 站点语言环境
# 中文博客建议设为 "zh"，英文博客保持 "en-us"
locale = "zh"
# 站点标题，显示在浏览器标签页和页面头部
title = "我的博客"
# ========================
# 国际化 / 语言设置
# ========================
# 默认内容语言
# 与 locale 保持一致，中文设为 "zh"
defaultContentLanguage = "zh"
# 是否包含 CJK（中日韩）语言
# 写中文博客务必设为 true
# 否则 .WordCount（字数统计）和 .ReadingTime（阅读时间）会按英文单词计算，结果严重不准
hasCJKLanguage = true
# ========================
# 主题设置
# ========================
# 指定主题文件夹名称（对应 themes/ 目录下的文件夹名）
# 如果你用 git clone 安装到了 themes/hugo-theme-stack，这里填 "hugo-theme-stack"
# 注意：使用 theme 字段后，应删除 [[module.imports]] 段落，避免冲突
theme = "hugo-theme-stack"
# ========================
# 分页设置
# ========================
[pagination]
# 每页显示的文章数量
# 首页、分类页、标签页等列表页面每页展示的文章数
# 建议 5~10，太少了翻页频繁，太多了加载慢
pagerSize = 5
# ========================
# 永久链接格式
# ========================
[permalinks]
# 文章（post）的URL格式
# /:slug/ 表示使用文章的 slug（即文件夹名或手动指定的别名）作为路径
# 例如 content/post/hello-world/index.md → /p/hello-world/
# 你可以改成其他格式，如 /:year/:month/:slug/ 或 /:sections/:slug/
post = "/:slug/"
# 固定页面（page）的URL格式
# 例如 content/page/about.md → /about/
page = "/:slug/"
# ========================
# 评论系统（可选）
# ========================
# Disqus 评论系统配置
# 如果不需要评论功能，可以注释掉或删除整个 [services.disqus] 段落
# 也可以替换为其他评论系统（如 Twikoo、Waline 等国内友好的方案）
#[services.disqus]
# 你在 Disqus 上注册的站点 shortname
# 不需要评论时注释掉此行即可
#shortname = ""
|
6.本地启动博客预览
配置完成后，执行启动命令，运行本地开发服务：
1
2
|
# 启动本地预览服务，渲染草稿文章
hugo server -D
|
启动成功后，打开浏览器访问 http://localhost:1313，即可看到完整的 Stack 主题博客页面。
好了 剩下的时间就留给各位自行探索了
