从空目录到上线：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