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

技术选型

考虑使用静态网站生成器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多星的项目会这么麻烦，可能还是没太明白它的设计原则。