博客 on 日常

排版效果展示

Sat, 11 Apr 2026 04:00:00 +0000

演示文章

使用 hugo new content post/example/index.md 命令创建了这篇文章。

代码

行内代码：Python 的列表推导式 python [x**2 for x in range(10)] 可以快速生成平方数列。

块级代码：

1
2
3
4
5
6
7


def fibonacci(n):
 a, b = 0, 1
 for _ in range(n):
 a, b = b, a + b
 return a

print(fibonacci(10)) # 55

不同语言不同高亮

1
2
3


[markup.highlight]
 noClasses = false
 lineNos = true

公式

行内公式：质能方程 $E = mc^2$，欧拉公式 $e^{i\pi} + 1 = 0$。

块级公式：

$$ \int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi} $$

带编号的公式：

$$ \mathbf{A} = \begin{bmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{bmatrix}, \quad \det(\mathbf{A}) = a_{11}a_{22} - a_{12}a_{21} \tag{1.2} $$

引用

任何足够先进的技术，都与魔法无异。

—— 亚瑟·C·克拉克

💡 提示

带标识的引用，这里是TIP

表格

语法	说明	示例
`斜体`	斜体文本	italic
`粗体`	粗体文本	bold
`代码`	行内代码	`code`
$公式$	行内公式	$x^2$

分割线

分割线宽度设置为 70% ，更自然

分割线下方的内容。

多级标题

三级标题

注意到右侧显示了本文的目录。

四级标题

正文内容。

五级标题

正文内容。

[EOF]

【从零开始的博客生活 - 3】Hugo&Stack用户此生必做的自定义修改

Sat, 11 Apr 2026 03:00:00 +0000

很好，少年，选择了Hugo和Stack主题，你就成功了一半。而行百里者半九十，剩下的就是不断的调整细节，优化功能和样式。这里给出了一份我认为的最佳实践，跟着做，你就成功了。

1. 行内公式 $...$ 格式与默认数学渲染

Stack 主题的数学公式渲染基于 Hugo 的 Goldmark passthrough 机制。默认配置：

支持块级公式：\[...\] 和 $$...$$
支持行内公式：$...$
默认每篇文章需在 front matter 中手动添加 math: true 才能渲染公式

$E = mc^2$ 这种单美元符号写法是 LaTeX 社区最普遍的行内公式格式。更重要的是它只有一个符号输入更快捷。

修改 hugo.toml以支持单美元符号写法：

1
2
3
4
5
6


[markup.goldmark.extensions.passthrough.delimiters]
 block = [["\\[", "\\]"], ["$$", "$$"]]
 inline = [["\\(", "\\)"], ["$", "$"]]

[params.article]
 math = true

调整后三种行内公式写法都能正确渲染：

写法	示例	渲染效果
`$...$`	`$E = mc^2$`	$E = mc^2$
$...$	$E = mc^2$	$E = mc^2$
`\[...\]`	`\[E = mc^2\]`	\[E = mc^2\]
`$$...$$`	`$$E = mc^2$$`	$$E = mc^2$$

同时我们通过params.article给所有文章默认开启了数学渲染。如果某篇文章不需要，可以单独关闭（不会有人这么无聊吧）：

1
2
3
4


---
title: "纯文本文章"
math: false
---

⚠️ 警告

单美元符号可能误匹配普通文本中的货币符号（如"售价 $5"）。技术博客中这个问题很少出现

开启后所有页面都会加载 KaTeX 资源（CSS + JS），对纯文本文章有非常非常轻微性能影响

2. 精简页脚版权行

Stack 主题默认页脚太单调，必须改一改。

这涉及到修改主题的footer模板。但是我们无论何时都尽可能不去动./theme/下的文件，而是利用 Hugo 的机制进行覆盖。

Hugo 的模板查找顺序是项目目录优先于主题目录，直接创建 layouts/_partials/footer/footer.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{{- $ThemeVersion := "4.0.0" -}}
<footer class="site-footer">
 <section class="copyright">
 &copy;
 {{ if and (.Site.Params.footer.since) (ne .Site.Params.footer.since (int (now.Format "2006"))) }}
 {{ .Site.Params.footer.since }} -
 {{ end }}
 {{ now.Format "2006" }} {{ default .Site.Title .Site.Copyright }} - Powered by
 <a href="https://gohugo.io/" target="_blank" rel="noopener"><b>Hugo</b></a> &amp;
 <a href="https://github.com/CaiJimmy/hugo-theme-stack" target="_blank" rel="noopener" data-version="{{ $ThemeVersion }}"><b>Stack</b></a>
 </section>
 ...
</footer>

调整后效果：

© 2026 日常 - Powered by Hugo & Stack

3. 访客统计与 ICP 备案

Stack 主题默认没有站点访客统计功能，也没有国内网站常见的 ICP 备案号展示位置。

1. 修改页脚模板 layouts/_partials/footer/footer.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{{- $ThemeVersion := "4.0.0" -}}
<footer class="site-footer">
 ...

 <section class="powerby">
 <span id="busuanzi_container_site_uv" style="display:none">
 Waiting for No.<span id="busuanzi_value_site_uv"></span>
 </span>
 {{ with .Site.Params.footer.icp }}
 <br/>
 <a href="https://beian.miit.gov.cn" target="_blank" rel="noopener" class="footer-icp">{{ . }}</a>
 {{ end }}
 </section>
</footer>

<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

2. 添加配置 在 hugo.toml 中：

1
2
3


[params.footer]
 since = 2026
 icp = "粤ICP备xxxxxxxx号-1"

3. 添加 ICP 样式 在 assets/scss/custom.scss 中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


.footer-icp {
 color: var(--body-text-color);
 opacity: 0.5;
 font-size: 1.1rem;
 text-decoration: none;
 font-weight: normal;
}

.footer-icp:hover {
 text-decoration: none;
}

调整后效果

页脚显示访客统计（不蒜子服务，脚本加载成功后自动显示）
显示 ICP 备案号，小号灰色字体，不喧宾夺主

💡 提示

不蒜子是第三方免费服务，几乎是统计访问量的最简单解决方案，很推荐。

4. 禁用目录列表自动编号

Hugo 的 markup.tableOfContents 默认使用有序列表 <ol>，浏览器会自动给目录项添加编号。

如果文章标题本身带有编号（如 “1. 引言”），目录就会产生重复编号：

1
2
3


1. 1. 引言
 1.1 1.1 背景
2. 2. 正文

我们修改 hugo.toml，将ordered设置为false：

1
2
3
4


[markup.tableOfContents]
 endLevel = 4
 ordered = false
 startLevel = 2

调整后目录变为无序列表，干净地显示 “1. 引言” 而非 “1. 1. 引言”。

5. 调整目录行间距

目录项的默认行间距较大。目录过长时会占用过多垂直空间，视觉不够紧凑。

在 assets/scss/custom.scss 中添加：

1
2
3
4


.toc-nav li {
 margin-top: var(--spacing-xs) !important;
 margin-bottom: var(--spacing-xs) !important;
}

目录行间距变小，更加紧凑，显示更多内容。

调整前	调整后

6. 调整代码块样式

代码块样式存在两个问题：

代码块有上下内边距，导致代码区域显得过于宽松
代码块缺乏边框，与正文区分不够明显

我们在 assets/scss/custom.scss 中添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


/* 代码块：取消上下padding，增加浅灰边框 */
.article-content .highlight {
 padding: 0 var(--card-padding);
 border: solid 2px #eeeeee;
}

/* 复制代码按钮同步调整位置，上偏移设为0 */
.copyCodeButton {
 top: 0 !important;
}

调整后

代码块上下内边距归零，更加紧凑
浅灰边框（#eeeeee）使代码块与正文有清晰的视觉分隔

7. 样式微调

正文和页面有以下问题

1.5em 的间距过大，显得松散
各处硬编码，无法统一调整
引用块字号与正文相同，缺乏层次感
菜单图标与文字之间存在过大的间距
分割线默认100px，大多数情况下过短

这些复杂样式问题涉及静态 CSS与动态配置的结合。首先核心原理：

Hugo 模板的变量注入：SCSS 文件不会被 Hugo 当作模板执行，无法直接使用 .Site.Params 读取配置。因此需要在 HTML 模板中通过 <style> 标签注入 CSS 变量。
文件作用：
- layouts/_partials/head/custom.html：Hugo 会在每个页面头部引入此模板。我们在这里注入 CSS 变量，读取 hugo.toml 中的 paraSpacing 参数。这里实际上具有一般html元素的地位，因此是个可以进行任何注入（js，css，css变量，DOM节点）的操作点位。
- assets/scss/custom.scss：传统的样式覆盖文件，使用 CSS 变量而非硬编码值。

工作流程：

1
2
3
4
5


hugo.toml 参数 
 ↓
layouts/_partials/head/custom.html 注入 CSS 变量
 ↓
assets/scss/custom.scss 使用变量覆盖主题样式

调整方案

可以看到主题中多个元素的纵向 margin 硬编码为 1.5em：

article-content > p（正文段落）
article-content blockquote（引用块）
article-content .gallery（图片画廊）
article-content table（表格）

我们将这些改为引用 hugo.toml 中的 paraSpacing 参数：

1
2


[params]
 paraSpacing = "1em"

创建变量注入模板，这一步很关键，我们实际上是在向最终html页面直接注入代码。新建 layouts/_partials/head/custom.html：

1
2
3
4
5
6
7


<style>
 :root {
 --para-spacing: {{ .Site.Params.paraSpacing | default "1em" }};
 --quote-font-size: 0.875em;
 --menu-icon-separation: 15px;
 }
</style>

这个文件会被主题自动引入到每个页面的 <head> 中，将 Hugo 配置转换为 CSS 变量。

变量说明：

--para-spacing：控制段落、引用块等元素的纵向间距
--quote-font-size：控制引用块字号（默认 0.875em，比正文略小）
--menu-icon-separation：控制侧边栏菜单图标与文字的间距（主题默认 40px，改为 15px 更紧凑）

然后使用变量覆盖样式，在 assets/scss/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


/* 注意：CSS变量 --para-spacing 和 --quote-font-size 在 layouts/_partials/head/custom.html 中定义 */

/* 正文段落间距 */
.article-content > p {
 margin-top: var(--para-spacing) !important;
 margin-bottom: var(--para-spacing) !important;
}

/* 引用块：间距+字号 */
.article-content blockquote {
 margin-top: var(--para-spacing) !important;
 margin-bottom: var(--para-spacing) !important;
 font-size: var(--quote-font-size);
}

/* 画廊间距 */
.article-content .gallery {
 margin-top: var(--para-spacing) !important;
 margin-bottom: var(--para-spacing) !important;
}

/* 表格间距 */
.article-content table {
 margin-top: var(--para-spacing) !important;
 margin-bottom: var(--para-spacing) !important;
}

/* 分割线宽度 */
.article-content hr {
 width: 70%;
}

调整后效果：

四处元素的纵向 margin 统一由 paraSpacing 参数控制，默认 1em，视觉更紧凑
引用块字号缩小为 0.875em，与正文形成层次对比
侧边栏菜单图标与文字间距从默认 40px 减小到 15px，更加紧凑
后续如需调整间距，只需修改 hugo.toml 中一个参数，无需改动多处 CSS
分割线宽度调整为 70%，相比于默认的 100px 更加适中

8. 修改文章模板 frontmatter 格式

hugo new content 命令使用 archetypes/default.md 作为模板创建新文章。Stack 主题默认生成的 frontmatter 使用 TOML 格式：

1
2
3
4
5


+++
date = '2026-04-11T12:00:00+08:00'
draft = true
title = 'My New Post'
+++

存在的问题

TOML 格式使用 +++ 分隔符，与社区更常用的 YAML 格式（---）不一致
draft = true 导致每篇新文章默认都是草稿状态，需要手动改为 false 才会发布

修改 archetypes/default.md：

1
2
3
4
5


---
date: '{{ .Date }}'
draft: false
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
---

调整后新创建的文章使用 YAML 格式，且默认不是草稿：

1
2
3
4
5


---
date: '2026-04-11T12:00:00+08:00'
draft: false
title: 'My New Post'
---

修改文件汇总

文件路径	修改内容
`hugo.toml`	增加 $...$ 行内公式、禁用目录编号、全局开启数学渲染、添加 `paraSpacing` 参数和 ICP 备案号配置
`archetypes/default.md`	frontmatter 格式改为 YAML，draft 默认 false
`layouts/_partials/footer/footer.html`	精简页脚版权信息，添加不蒜子访客统计和 ICP 备案号展示
`layouts/_partials/head/custom.html`	新建，注入 CSS 变量 `--para-spacing` 和 `--quote-font-size`
`assets/scss/custom.scss`	添加 ICP 样式、目录行间距、代码块样式（边框+复制按钮位置）、段落/元素间距、引用块字号的覆盖样式

【从零开始的博客生活 - 2】让博客看起来像Stack的demo一样具有完善的功能

Sat, 11 Apr 2026 02:00:00 +0000

Hugo 的 Stack 主题功能丰富，但官方 Demo 采用了目录式配置（config/_default/ 下拆分 6 个 TOML 文件），对新手来说拼凑出完整配置并不容易。本文记录了从近乎空白的 hugo.toml 出发，一步步配置出完整 Stack 博客的过程，目标是让读者照做即可获得同样的效果。

最终效果：左侧边栏显示头像和社交链接图标，顶部菜单包含主页/关于/归档/搜索/链接五个入口，首页右侧有搜索/归档/分类/标签云小部件，文章页支持数学公式渲染和自动目录。

1. 安装 Hugo 和 Stack 主题

之前的文章里讲过了，大概就是：

1
2
3
4


hugo new site myBlog
cd myBlog
git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/hugo-theme-stack

添加 .gitignore：

1
2
3


public/
resources/
.hugo_build.lock

在 hugo.toml 中声明主题：

1

theme = "hugo-theme-stack"

2. 理解 Stack 的菜单机制

这是配置中最容易踩坑的地方：Stack 的左侧菜单项不是在 hugo.toml 中定义的，而是通过各内容页面的 front matter menu.main 字段声明的。

也就是说，你需要在 content/ 下创建对应的页面文件，每个页面的 front matter 中指定菜单名称、权重和图标，Hugo 会自动收集这些信息生成菜单。

3. hugo.toml 完整配置

以下是完整的 hugo.toml，每一段都有注释说明作用：

 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
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101


baseURL = "https://example.org/"
languageCode = "zh-cn"
title = "你的博客标题"
theme = "hugo-theme-stack"
defaultContentLanguage = "zh"
hasCJKLanguage = true

# 分页：每页显示文章数
[pagination]
 pagerSize = 5

# 文章 URL 格式
[permalinks]
 post = "/p/:slug/"
 page = "/:slug/"

# 中文语言配置
[languages.zh]
 languageName = "简体中文"
 title = "你的博客标题"
 weight = 1
 [languages.zh.params.sidebar]
 subtitle = "你的副标题"

# Markdown 渲染配置
[markup]
 [markup.goldmark]
 [markup.goldmark.extensions]
 # 数学公式 passthrough：让 $$...$$ 和 \(...\) 原样传递给前端渲染
 [markup.goldmark.extensions.passthrough]
 enable = true
 [markup.goldmark.extensions.passthrough.delimiters]
 block = [["\\[", "\\]"], ["$$", "$$"]]
 inline = [["\\(", "\\)"]]
 # 允许原始 HTML（部分 shortcode 需要）
 [markup.goldmark.renderer]
 unsafe = true
 # 文章目录：从 h2 到 h4，有序列表
 [markup.tableOfContents]
 endLevel = 4
 ordered = true
 startLevel = 2
 # 代码高亮
 [markup.highlight]
 noClasses = false
 codeFences = true
 guessSyntax = true
 lineNos = true
 lineNumbersInTable = true
 tabWidth = 4

# 主题参数
[params]
 mainSections = ["post"] # 首页展示的文章分类
 rssFullContent = true
 favicon = "img/avatar.png" # 站点图标，路径相对于 assets/

 [params.footer]
 since = 2026 # 建站年份

 # 侧边栏：头像、副标题、emoji
 [params.sidebar]
 emoji = "✏️" # 头像下方显示的 emoji ，可置空。有谁知道这玩意到底有什么用？
 subtitle = "你的副标题"
 avatar = "img/avatar.png" # 头像，路径相对于 assets/

 # 文章许可协议
 [params.article]
 [params.article.license]
 enabled = true
 default = "Licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)"

 # 小部件：首页和文章页分别显示什么
 [params.widgets]
 homepage = [
 { type = "search" },
 { type = "archives", params = { limit = 5 } },
 { type = "categories", params = { limit = 10 } },
 { type = "tag-cloud", params = { limit = 10 } },
 ]
 page = [{ type = "toc" }] # 文章页显示目录

 # 评论（暂不启用）
 [params.comments]
 enabled = false

# 社交链接图标（显示在侧边栏头像下方）
[[menus.social]]
 identifier = "github"
 name = "GitHub"
 url = "https://github.com/你的用户名"
 [menus.social.params]
 icon = "brand-github"

# 可继续添加更多社交链接，例如：
# [[menus.social]]
# identifier = "twitter"
# name = "Twitter"
# url = "https://twitter.com/你的用户名"
# [menus.social.params]
# icon = "brand-twitter"

关键配置解读

配置项	作用	注意点
`params.sidebar.avatar`	侧边栏头像	图片放在 `assets/img/` 下
`menus.social`	社交链接图标	图标名来自 Tabler Icons，前缀 `brand-`
`markup.goldmark.extensions.passthrough`	数学公式	让 `$$...$$` 和 `$...$` 不被 Markdown 引擎转义
`markup.tableOfContents`	目录范围	h2 到 h4 是比较合理的层级
`params.widgets`	首页/文章页小部件	首页放搜索/归档/分类/标签云，文章页放 TOC

4. 创建内容页面

每个页面的 front matter 中 menu.main 定义了它在左侧菜单中的显示。weight 越小越靠前，icon 对应 Tabler Icons 图标名。

本节很长，但好消息是本节也很水。

4.1 首页 — `content/_index.md`

1
2
3
4
5
6
7
8


---
menu:
 main:
 name: 主页
 weight: -100
 params:
 icon: home
---

4.2 关于 — `content/page/about/index.md`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


---
title: 关于
description: 关于本站及其作者
menu:
 main:
 weight: -90
 params:
 icon: user
---

## 关于本站

在这里写你的介绍。

4.3 归档 — `content/page/archives/index.md`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
title: 归档
layout: "archives"
slug: "archives"
menu:
 main:
 weight: -70
 params:
 icon: archives
---

注意 layout: "archives" 是 Stack 主题提供的特殊布局，会自动按时间线展示所有文章。

4.4 搜索 — `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
---

outputs: [html, json] 是搜索功能的必要配置，Stack 主题的搜索依赖 JSON 索引。

4.5 链接 — `content/page/links/index.md`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


---
title: 链接
description: 友情链接
menu:
 main:
 weight: -50
 params:
 icon: link
links:
 - title: GitHub
 description: 全球最大的软件开发平台
 website: https://github.com
 image: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png

comments: false
---

在这里可以添加友情链接。在 front matter 的 `links` 字段中配置即可。

links 字段是 Stack 主题的友情链接功能，每项包含 title、description、website、image。

5. 放置头像

将头像图片放到 assets/img/avatar.png，与配置中 params.sidebar.avatar = "img/avatar.png" 对应。

Hugo 会自动从 assets/ 目录查找资源文件，所以配置路径是相对于 assets/ 的。

6. 数学公式渲染

配置分两层：

hugo.toml 中的 passthrough（已在上面配置）：让 Markdown 引擎不处理 $$...$$ 和 $...$，原样输出到 HTML
文章 front matter 中启用：每篇需要数学公式的文章，在 front matter 中添加 math: true

示例文章 front matter：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
title: "一篇数学文章"
math: true
---

行内公式 $E = mc^2$，块级公式：

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Stack 主题会在检测到 math: true 时自动加载 KaTeX 渲染引擎。

7. 文章目录

已经在 hugo.toml 中配置了：

markup.tableOfContents：定义 TOC 的标题层级范围（h2-h4）
params.widgets.page = [{type = "toc"}]：文章页右侧自动显示 TOC 小部件

无需在文章 front matter 中额外配置，所有文章都会自动显示目录。

8. 菜单图标

左侧菜单图标和社交链接图标使用 Tabler Icons。图标被Stack放在 assets/img/icons/ 目录下，可以直接使用。也可以去Tabler官网下载SVG图标放到自己的图标文件夹里(./assets/icons)使用。

比如说，非常离谱，默认是没有mail图标的，你得自己下一个才方便在主页放一个自己的邮箱按钮。

9. 最终目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


myBlog/
├── hugo.toml
├── assets/
│ ├── img/
│ │ └── avatar.png
│ └── icons/
│ └── mail.svg
├── content/
│ ├── _index.md
│ ├── page/
│ │ ├── about/index.md
│ │ ├── archives/index.md
│ │ ├── search/index.md
│ │ └── links/index.md
│ └── post/
│ └── ... (你的文章)
└── themes/
 └── hugo-theme-stack/ (git 子模块)

10. 预览

1

hugo server

打开 http://localhost:1313 即可查看效果。确认无误后，用 hugo 命令生成静态文件到 public/ 目录。

【从零开始的博客生活 - 1】Hugo 初见与 Stack 主题

Sat, 11 Apr 2026 01:00:00 +0000

技术选型

考虑使用静态网站生成器hugo，因为CMS实在是太重了，反正都要在电脑上写作，写作端干脆采用更灵活的方案，例如vscode或者总是被推荐的typora，思源笔记等。而博客前端则主要考察发布过程是否方便，主题样式是否合眼，文档和讨论的支持是否丰富。

在考察过程中发现 EdgeOne Page 静态托管支持 Hugo ，也就是说不用采用经典的依附于 GitHub Action 和 GitHub Pages 的方案，可以直接在 EdgeOne Page 上 CI/CD ，并提供给国内用户访问，这一点就很方便。

Hugo主题站还算丰富，看到一个 Stack 主题很符合我的需求。Hugo 和 Stack 都有丰富的生态讨论环境，Stack 还有中文文档（虽然看下来发现非常简陋机翻），所以就这样吧。

不过上手了才发现坑还是巨多。不明白为什么这么一个成熟的应用领域还这么不完善。

下载安装

Hugo 是一个静态站点生成器，虽然最终构建通常由 CI/CD 执行，但本地安装便于预览和调试，通常也是必要的。

Windows 安装步骤：

从 Hugo Releases 下载对应版本的压缩包
解压后将 hugo.exe 所在目录添加到系统 PATH，例如 E:\Program Files\hugo

终端选择：

Hugo 官方推荐使用 Bash 或 PowerShell 7+，不建议使用 CMD 或 Windows PowerShell 5.x。若要在 VS Code 集成终端中使用 PowerShell 7，可添加以下配置：

1
2
3
4
5
6


"terminal.integrated.profiles.windows": {
 "PowerShell 7": {
 "path": "pwsh.exe",
 "icon": "terminal-powershell"
 }
}

创建站点

执行以下命令初始化博客：

1
2
3


hugo new site my-site # 创建站点骨架
cd my-site
git init # 初始化 Git 仓库

注意： 执行命令的位置不重要，关键是 my-site 目录所在的位置才是真正的项目根目录。

创建完成后，项目目录会生成基础文件结构，其中 ./hugo.toml 是核心配置文件。

创建一个.gitignore文件先把构建产出等乱七八糟的东西屏蔽掉，内容如下：

1
2
3


public/
resources/
.hugo_build.lock

安装主题

从 Hugo 主题商店选择心仪的主题，在项目根目录下使用 PowerShell 通过 Git Submodule 安装：

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

然后在 ./hugo.toml 中启用主题：

theme = “hugo-theme-stack”

直接从主题官方仓库拉取的好处是可以接收主题作者的后续更新。你也可以先fork到自己的仓库，以便于后续自定义样式可以提交到仓库。当然，这样做之后，如果你还想拉取作者后续更新，就可能需要处理git冲突了。

创建第一篇内容

创建内容和创建第一篇内容的区别就在于，第一次时总是有这样那样的配置需要搞一搞，以后就慢慢顺了。说起来还挺烦的。

创建内容

使用 hugo new content post/first/index.md 创建第一篇内容。注意 Stack 主题要求文章放在 post 而不是 posts 目录下，不要写错。

Frontmatter 是文章的元数据，不过没有流行的中文翻译，姑且叫他前置设置吧。一般包括标题、日期、标签等。例如本文的配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
date: 2026-04-11 01:00:00
draft: false
title: "【从零开始的博客生活 - 1】Hugo 初见与 Stack 主题"
description: "今天起成立了"
tags: ["Hugo", "Stack"]
categories: ["技术", "博客"]
image: "蓝毒.jpg"
math: true
---

你可能会发现自己的配置头与本文的不太一样。这是因为我后续又调整了 hugo new 的行为，默认采用yaml格式配置头。

说一下几个字段：

draft：是否为草稿。默认值为 true。主要作用是让你别误发布了尚处于草稿阶段的文章。但是没卵用，因为Hugo根本没有内容管理能力，任何一个对数据安全稍有负责心的作者都应该使用笔记软件或其他东西来确保自己的草稿不意外丢失，等进入 Hugo 构建阶段了基本就是要发布了。
math：是否开启数学公式支持。这是通过 Stack 主题提供的 $\rm K^AT_EX$ 能力来实现的。其实也可以通过配置渲染穿透和MathJax来实现，不过现在这样看起来也够用就暂时不再折腾了。Katex比MathJax轻量级且快。推荐全局开启，文章头就不用写了。
description：文章的描述，同时会写在文章标题下方，在文章页和文章列表页显示，实际上类似副标题的地位。
tags：文章的标签，用于分类和搜索。除了主页分类，tags还会被写入文章页面的 <head> 中，对SEO有帮助。

Markdown 语法就不说了。可以看demo里提供的一个示例文章，很详细。

完事就使用 hugo server 查看效果，默认会渲染到 http://localhost:1313 。这个渲染是即时的，类似于 npm run dev ，可以在调整了文章内容或配置后立即看到效果。按照官方的说法，“这个过程相当快，你应当察觉不到页面被重渲染了”。

你说的这个 demo ，它在哪啊？

在.\themes\hugo-theme-stack\demo\

Stack 主题有一个 demo 目录，里面包含了一些示例文章，同时也是重要的参考文档。有个 themes\hugo-theme-stack\demo\run.sh 告诉我们这样启动它：

1

hugo server --gc --themesDir=../..

但是这是不行的，因为在 themes\hugo-theme-stack\demo\config_default\hugo.toml Line 11 中有个错误：

1
2


[[module.imports]]
 path = "github.com/CaiJimmy/hugo-theme-stack/v3"

这个设置指明通过 Hugo Module 来引入主题，但是我们的主题是通过 Git Submodule 安装的，所以这里需要改为：

1

theme = "hugo-theme-stack"

然后再在.\themes\hugo-theme-stack\demo\启动命令行输入hugo server --gc --themesDir=../..就可以预览了。

为什么Stack这么麻烦

小编也不知道为什么一个6.3k多星的项目会这么麻烦，可能还是没太明白它的设计原则。

写法	示例	渲染效果
`\(...\)`	`\(E = mc^2\)`	\(E = mc^2\)
$...$	$E = mc^2$	$E = mc^2$
`\[...\]`	`\[E = mc^2\]`	\[E = mc^2\]
`$$...$$`	`$$E = mc^2$$`	$$E = mc^2$$