Helloblog

配置指南

Sat, 07 Nov 2026 00:00:00 +0800

配置指南#

本页说明主题的配置该怎么写：哪些由主题内置、哪些必须写在你的站点里、每个参数的作用，以及容易踩的坑。按顺序抄一遍就能跑起来。

配置分三层#

文件	作用	要不要动
主题根 `hugo.toml`	主题内置默认值，Hugo 会自动合并进你的站点	不用动，需要时在站点里覆盖
站点 `hugo.toml`	你自己的站点配置	必须写
`exampleSite/hugo.toml`	示例站配置，含仓库自测用的挂载	只作参考

警告

不要把 exampleSite/hugo.toml 整份复制到自己的站点。它的 [module] 段挂载的是 ../layouts、../assets 这些上层目录，只有「仓库根就是主题」的结构才成立。主题安装到 themes/helloblog 后这些路径不存在，构建会直接失败。

最小可用配置#

初始化站点只需要下面这些：

baseURL = 'https://your-domain.com/'
title = 'My Blog'
timeZone = 'Asia/Shanghai'
theme = 'helloblog'

# 生成 robots.txt，并指向 sitemap
enableRobotsTXT = true

# 标签只在 /tags/ 原地筛选，不生成 /tags/<term>/ 详情页
disableKinds = ['term']

# 首页额外输出 index.json，搜索功能依赖它
[outputs]
 home = ['html', 'rss', 'json']

# 列表页每页条数
[pagination]
 pagerSize = 6

# 只保留标签 taxonomy
[taxonomies]
 tag = 'tags'

警告

outputs.home 必须包含 json。少了它，搜索会静默失效，页面不报错但没有任何结果。

静态博客的写作组件与排版实践

Fri, 23 Oct 2026 00:00:00 +0800

写博客久了会发现，真正影响阅读体验的往往不是内容本身，而是排版：代码块有没有高亮、提示信息会不会被忽略、长文能不能快速跳转。这篇示例文章用来说明本主题的写作组件是怎么设计、怎么用的，也可以当作新文章的模板参考。

为什么把渲染放在编译期#

静态站点最容易被误解的一点，是「静态等于没有交互」。实际上交互可以保留，只是执行位置不同。

核心原则

能在构建时确定的内容，就不要留到浏览器再算。

具体到本主题，Markdown 里的提示块、目录树、终端输出、流程图外壳都在构建时直出 HTML；只有 mermaid 绘图、代码复制、图集灯箱这类依赖浏览器能力的部分才留了少量脚本。

任何可以用编译期解决的问题，都不应该留给运行时。
设计原则《项目手册》

这样做的好处很直接：首屏是完整的 HTML，搜索引擎和 RSS 读到的内容和读者看到的一致，也不会因为脚本加载失败而白屏。代价是改内容需要重新构建，对个人博客来说几乎不算成本。

写作流程#

新增一篇文章的步骤是固定的：

建目录

在 content/posts 下按 slug 建文件夹

写正文

新建 index.md，可配 index.en.md 提供译文

本地预览

hugo server 实时查看效果

发布构建

hugo --minify 输出静态文件

本地预览只需一条命令：

terminal

$ cd exampleSite

$ hugo server

Web Server is available at http://localhost:1313/

$ hugo --minify

信息

本地预览默认端口是 1313，被占用时加 -p 换一个即可；构建产物不会包含 Draft 状态的文章。

关于我

Mon, 01 Jan 0001 00:00:00 +0000

关于我#

个人简介#

就读于东北电力大学，专业为电气工程及其自动化。

对编程感兴趣，自学了点编程。

技术栈#

前端：HTML5、CSS3、TypeScript（JavaScript）、Vue3、SSG（Hexo、Hugo、VitePress）
后端：Python、TypeScript
硬件：Arduino（Cpp）、STM32（C）
工具：Vite、Git、npm

联系方式#

邮箱：3253884026@qq.com
GitHub：https://github.com/Cnkrru

关于 AI 编程#

我不反感 AI 编程，但是不喜欢 All in AI
根据个人使用 AI 编程的体验来看，AI 能发挥多大能力取决于你自己的知识储备和代码水平
不管是前端、后端还是硬件，在 AI 辅助下，确实轻松了不少，但是目前 AI 写的代码，感觉和屎山差不多
不多说了，AI 是好事，但是不管做什么还是得看个人水平

这个博客站点的所有文章以及示例代码均是手写
说这个不是为了炫耀什么，该博客中所有文章涉及的内容如有疑问，随便问我，可能我会记不清楚具体的解决方法，但是自己写过的总会有印象

AI 写的最好自己看看，写的不好，经过人工审查后，一些模块代码能减少 50%，一些是代码精简，但是功能保持不变，一些是死代码