Hugo on IMX 示例站

留一方安静的屏幕：认识 IMX

Wed, 15 Jul 2026 12:00:00 +0800

有些博客急于展示自己：色彩先于文字抵达，动画比段落更早开口。IMX 选择了另一条路。它愿意向后退半步，把屏幕还给文章，把注意力留给那些需要慢慢读完的句子。

这是一款为中文博客而写的 Hugo 主题。它有清楚的内容结构，也有搜索、目录、代码高亮和评论这些现代站点需要的能力；但它并不想把功能一项项摆在读者面前。多数时候，它只是安静地托住内容。

一场克制的相遇

打开 IMX，最先感受到的不是某一种强烈风格，而是一种经过整理的秩序。

暖白背景带着纸张的温度，炭黑文字保留足够的分量，棕色与冷灰只在边缘轻轻出现。卡片有阴影，却不悬浮得盛气凌人；玻璃质感藏在导航与控件里，却没有把页面变成一场材质展览。那枚雪花既是标记，也像一处停顿，让理性的技术页面多了一点冬日的清澈。

这种克制并不等于寡淡。恰恰因为装饰被控制在合适的音量，图片、标题与正文才有了各自的位置。读者进入页面后，不必先学会如何使用它，视线自然会落到文章上。

阅读始终是第一件事

IMX 对长文格外友好。

正文保持舒展的行宽，中文衬线字体让连续阅读更接近纸面，标题、引用、表格和代码块之间有清楚的节奏。文章足够长时，目录会守在一旁，随着阅读进度标出当前位置；屏幕变窄后，它又收进一个不打扰正文的入口。

界面、导航和标题统一使用 Inter，正文使用 Noto Serif SC 的 400 与 700 字重，代码另用等宽字体。字体都随主题自托管，文章页只提前加载最常用的正文字符，其余字符按内容需要补充，不会连接第三方字体服务。

代码复制、语言标识和阅读进度都已经准备妥当。它们并不抢眼，却会在真正需要时出现。技术文章因此不必在“好看”和“好用”之间反复取舍：一段代码可以保持准确，一篇散文也不会因此沾上工具页面的生硬。

光暗有自己的时间

深色模式常被当作一组相反的颜色，IMX 更愿意把它理解为阅读环境的变化。

白昼里，页面接近温暖的纸色；夜晚到来后，背景沉入柔和的灰黑，文字与边界随之收敛。主题按钮可以在浅色、深色和自动模式之间切换，自动模式依照东八区的时间，在清晨与傍晚完成交接。

Logo、favicon 与 Giscus 评论区会跟随实际主题一起变化。于是深浅色不只是正文背景的替换，而是一套从页面开始、延伸到站点细部的完整状态。

每篇文章都有来处

写作久了，真正困难的往往不是发布，而是寻找。

IMX 用文章、分类与标签整理内容。首页保留精选与最新文章：精选可以由作者显式指定，最新内容则始终按发布日期倒序，两个区域各自表达不同的阅读入口。分类呈现一条较长的脉络，标签则容纳那些更细小、更偶然的联系。

文章列表页内置搜索直接读取 Hugo 生成的 JSON 索引，不依赖外部服务，也不要求另建数据库。它可以从标题、正文、分类和标签中寻找内容，并把更接近标题与主题的结果排在前面。这个入口只服务文章列表，不会扩展成覆盖每一种页面的全站搜索。

这样的结构足够简单，不会让写作者在发布前填写一长串字段；又足够清楚，让几年后的读者仍能从一篇旧文章走到同一主题下的其他文字。归档不是写作之后的杂务，而是内容逐渐形成形状的过程。

技术退到幕后

IMX 通过 Hugo Module 安装。站点不需要复制整套主题源码，也不需要为了日常构建安装前端工具链。CSS 由 Hugo Pipes 处理，JavaScript 由 Hugo 构建并生成指纹；普通写作者面对的仍然只是配置文件、Markdown 与图片。

这也让更新变得清楚。主题版本记录在 Go Module 中，需要时升级，遇到问题可以回到先前版本。Logo、头像、默认封面、分享图、菜单和页脚都能从站点配置中替换；更深入的定制，则可以利用 Hugo 的覆盖机制留在自己的仓库里。

技术没有消失，只是被放回了合适的位置。首页的字形动画会依据设备像素密度控制绘制规模，在离开视口时暂停，尺寸和主题变化也尽量复用已有状态。它负责让页面稳定、流畅、可以迁移，而不是要求写作者每天照看它。

评论可以有，也可以没有

一座博客不一定需要热闹。有人把它当作公开书房，只留下文章；也有人希望读者在文末继续谈话。

因此 IMX 默认关闭评论，但预留了 Giscus。启用后，评论保存在 GitHub Discussions 中，站点本身不需要维护数据库。评论框会懒加载，并跟随页面的深浅色状态。是否打开它，不是主题替你作出的决定，而是写作者对交流方式的选择。

从空目录到上线：hugo-theme-imx 全量配置手册

Wed, 15 Jul 2026 11:00:00 +0800

这篇手册按一个真实站点的顺序来写：先把环境和模块装好，再整理 hugo.toml、内容与图片，最后部署。文中的配置以 IMX 当前模板实际读取的参数为准，不把 Hugo 的数百项通用设置全部塞进来凑数。

如果只想先看效果，下载主题 Release 源码后，在主题目录运行：

hugo server --source exampleSite

但正式建站不要复制 exampleSite/go.mod。其中的 replace github.com/c-x-x/hugo-theme-imx => ../ 只为主题仓库本地开发服务，离开这个目录结构就会失效。

1. 环境与目录

IMX 通过 Hugo Module 安装，最低要求是 Hugo Extended 0.112.0 和 Go 1.20。先确认本机工具：

hugo version
go version
git --version

hugo version 的输出应包含 extended。普通建站不需要 Node.js，也不需要执行主题仓库里的 npm install；Node.js 和 Playwright 只是主题维护者跑回归测试时使用。

新站点可以这样开始：

hugo new site my-blog
cd my-blog
git init
hugo mod init github.com/your-name/my-blog

一个够用的目录大致如下：

my-blog/
├── archetypes/
├── assets/ # 覆盖主题 CSS 等资源时才需要
├── content/
│ ├── _index.md
│ ├── about.md
│ ├── categories/_index.md
│ ├── posts/_index.md
│ └── tags/_index.md
├── static/
│ └── images/
├── go.mod
├── go.sum
└── hugo.toml

public/ 和 resources/_gen/ 都是构建产物，不应当手工维护。建议加入 .gitignore：

把评论留在 GitHub：IMX 主题接入 Giscus

Wed, 15 Jul 2026 10:00:00 +0800

Giscus 不替你另建一套评论数据库。每篇文章的评论最终都是 GitHub Discussions 里的一个讨论，访客用 GitHub 账号登录后发言，站长仍在熟悉的仓库里管理内容。对静态博客来说，这套办法省心，也方便迁移。

IMX 已经把 Giscus 的加载、懒加载和深浅色同步写进主题。真正需要做的事只有两部分：先把 GitHub 仓库准备好，再把 giscus.app 生成的参数原样填进 hugo.toml。

开始前先选好评论仓库

评论可以放在博客源码仓库，也可以单独建一个仓库。个人站点我更倾向于单独建，例如 your-name/blog-comments：源码仓库的 Issues、Pull Requests 和 Discussions 不会混在一起，将来更换静态站点生成器，也不影响旧评论。

无论选哪一种，仓库都要满足三个条件：

仓库是公开仓库。Giscus 需要让访客读取讨论内容。
仓库已经启用 GitHub Discussions。
Giscus GitHub App 已获准访问这个仓库。

若仓库属于组织，安装 GitHub App 可能需要组织所有者批准。不要等到配置页一直报错才回头查权限。

第一步：开启 GitHub Discussions

进入评论仓库，依次打开 Settings → General → Features，勾选 Discussions。仓库顶部随后会出现 Discussions 标签。

第一次进入 Discussions 时，GitHub 会让你选择或创建讨论分类。IMX 示例配置使用 Announcements，但这不是硬性要求。你可以新建一个名为“博客评论”的分类，只要稍后在 giscus.app 里选择同一个分类即可。

建议把分类的格式设为 Open-ended discussion。如果使用公告类分类，还要确认普通访客能够在对应讨论下回复。

第二步：安装 Giscus App

打开 Giscus App 安装页，点击 Install，选择仓库所属的个人账号或组织。