Hugo Modules 从入门到放弃

所以，我想新起一个 Hugo 网站。假设我保留了几年以来使用 Hugo 的经验，那么，我能做到的最好（快速，简洁，易懂，DRY……）的方式，该是什么呢？

思考了一下，可能包括（但不限于）以下几点：

使用 Hugo Modules 管理主题及部件
把能独立出去的部件（包括 shortcode）全都独立出去以供复用
通过设置而不是覆盖文件来自定义站点

以下是一个最低限度的实践例。

新建站点

根据 Quick start | Hugo，先检查一下 Hugo 的版本。

hugo version
# hugo v0.115.2+extended darwin/amd64 BuildDate=unknown

超过要求的 v0.112.0 了，继续。

接下来创建站点。

hugo new site quickstart
# Congratulations! Your new Hugo site is created in ~/Documents/GitHub/quickstart.

# Just a few more steps and you're ready to go:

# 1. Download a theme into the same-named folder.
#    Choose a theme from https://themes.gohugo.io/ or
#    create your own with the "hugo new theme <THEMENAME>" command.
# 2. Perhaps you want to add some content. You can add single files
#    with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
# 3. Start the built-in live server via "hugo server".

# Visit https://gohugo.io/ for quickstart guide and full documentation.

请注意，这里的提示，以及 Quick start | Hugo 里接下来的步骤，不是我们接下来要做的事情。

接下来 cd 进去看看自动创建的文件。如果您跟我一样，已经用了几年 Hugo 的话，会发现原本叫 config.yaml／config.toml 的文件改名叫 hugo 了。我不是很习惯，但是这样明显更合适。

cd quickstart
tree -a -L 2 .
# .
# ├── archetypes
# │   └── default.md
# ├── assets
# ├── content
# ├── data
# ├── hugo.toml
# ├── layouts
# ├── static
# └── themes

# 8 directories, 2 files

添加主题

接下来参考 Use Hugo Modules | Hugo 和 Hugo Modules: Getting Started ❚ A Scripter’s Notes。

首先，检查一下 Go 的版本。

go version
# go version go1.22.1 darwin/amd64

超过要求的 1.12 了，继续。

接下来把站点转化为一个 Hugo Module，因为只有站点本身是 module 的时候，才能使用别的 module（包括但不限于主题）。

hugo mod init quickstart
# go: creating new go.mod: module quickstart
# go: to add module requirements and sums:
#         go mod tidy

接下来添加一个主题。任何包含了 go.mod 文件的主题都可以被用作 theme module，这里用 Quick start 给的 theNewDynamic/gohugo-theme-ananke 作为例子。

首先检查 theNewDynamic/gohugo-theme-ananke/theme.toml（别的 module 可能是 hugo.toml）里的 min_version 是否满足。

在 hugo.toml 里，添加：

[module]
  [[module.imports]]
    path = 'github.com/theNewDynamic/gohugo-theme-ananke'

然后使用以下命令下载：

hugo mod tidy

最后运行本地服务器，查看结果：

hugo server

检查此时的文件。

tree -a -L 2 .
# .
# ├── .DS_Store
# ├── .hugo_build.lock
# ├── archetypes
# │   └── default.md
# ├── assets
# ├── content
# ├── data
# ├── go.mod
# ├── go.sum
# ├── hugo.toml
# ├── layouts
# ├── resources
# │   └── _gen
# ├── static
# └── themes

# 10 directories, 6 files

使用 git（可选）

我有一个攒了很久的 .gitignore 文档，这里就直接用了。注意：需要保留 go.mod 和 go.sum。

# macOS
.DS_Store
.AppleDouble
.LSOverride

# hugo
.hugo_build.lock
/public/
_gen/
static/pagefind

创建 git repo：

git init
git add --all

（可选）在 GitHub 网页上创建空 repo，然后使用以下命令上传：

git remote add origin https://github.com/<user>/<site>.git
git branch -M main
git push -u origin main

部署到 Netlify（可选）

参考 Host on Netlify | Hugo，创建 netlify.toml。以下是一个最小例子：

[build]
publish = "public"
command = "hugo --gc --minify"

[build.environment]
HUGO_VERSION = "0.115.2"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

注意：需要把 go.mod 里的 go 1.22.1 改成 go 1.22（不要最后一个小版本），不然 Netlify 会报错。

以上。

优点和缺点

优点：

不需要纠结 git submodule
文件夹结构更简洁
可以使用 mounts

（还有别的吗？）

缺点：无法实时修改和预览主题。作为一个在网站上使用自己修改的主题的人，我装完才发现，啊这，这是个非常大的缺点……所以这篇文章很大可能不会有后续了（。

方案：混合使用传统主题安装方式和 Hugo Module？或许？（好麻烦……）