如何在 Hugo 中添加自定义 CSS

本文属于 Having fun with CSS 系列：

1. 总结一下 Blogger 的自定义 CSS
2. 如何在 Hugo 中添加自定义 CSS (本文)
3. 完美主义手残

本文属于 Deep dive into Hugo 系列：

1. 如何在 Hugo 中添加自定义 CSS (本文)
2. 深入探究 Hugo 代码高亮
3. 深入探究 Hugo 短代码
4. 续・深入探究 Hugo 短代码：我今天还就非得把这个脚注写出来不可

基本都是 rant，太长不想看的朋友可以直接拉到文章末尾看代码。

发现了这个，改天研究一下……：Best way to include JavaScript libraries in Hugo sites - support - HUGO

2021-05-10 更新：已经加入 layout。

这并不是我用 Hugo 做的第一个网站，但之前那个网站内容非常之单一，主题也是我随便挑了一个，几乎只改了颜色就直接用了。

那个主题是 Yihui 改过的，可以添加自定义 CSS 代码，head.html 里面的 layout 是这样的：

{{ range .Site.Params.customCSS }}
<link rel="stylesheet" href="{{ . | relURL }}">
{{ end }}

示例 config：

params:
  customCSS: 
    - "/css/1.css"
    - "/css/2.css"

示例 file tree：

static/
└── css
    ├── 1.css
    └── 2.css

这个方法代码简洁，逻辑清晰，可以说是什么都好，但是有一点不好：它跟 Hugo 的文件结构背道而驰，导致 Hugo 内置的很多方便的方程（比如 CSS minifier）无法使用。

我一直没怎么在意过这个事情，直到昨天查了一下怎么给单独页面添加 CSS（Using an additional specific css style for a page - HUGO），突然发现诶，别人添加自定义 CSS 的代码跟我的好像不太一样……

这位名为 Polarhardboiled 的网友是这么写的：

{{ with $.Resources.GetMatch "**.css*" }}
{{ $style := . | minify | fingerprint }}
<link type=text/css rel="stylesheet" href="{{ $style.Permalink }}">
{{ end }}

我第一反应是，哦，Hugo 好像是有内置 CSS minifier 方程的，那我也像她那样加上 | minify | fingerprint 不就行了？对不起，无论怎么写都是 Hugo server error。

首先点醒我的是这个 issue： Minification example not working · Issue #6646 · gohugoio/hugo。其中提到，Hugo 的 CSS 和 JS 文档（resources，哈¹）应该放在 assets/ 而不是 static/ 下面。

……？

好，那我把 css/ 挪到 assets/ 下面总行了吧？ 对不起，GetMatch 只能 get 到一个文件。我甚至不知道为什么这么重要的事情没有在 Hugo 文档的任何一页写到，而是藏在八百年前的一个 issue 里：The big assets handling / resource transformation funcs naming thread · Issue #4854 · gohugoio/hugo · GitHub

为表达我的愤慨，在此全文抄写该表格。事实上，最重要的前三个方程完全没有详细文档。人干事？恩？（注意大小写有意义，比如 Resources.GetMatch 和 resources.GetMatch 是两个不同的方程，大写的 Resources 是给 Page Bundle 用的。）

总之，浪费了一些生命，再学了一点 resources.Concat 之后，以下是最终版本：

{{ if .Site.Params.customCSS }}
{{ $style := resources.Match "css/**.css" | resources.Concat "custom.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}" integrity="{{ $style.Data.Integrity }}" media="screen">
{{ end }}

当然理论上也可以直接用 SCSS 啊，改一下 match，再在 minify 前加上 toCSS | 就可以了。

示例 config：

params:
  customCSS: true

示例 file tree：

assets/
└── css
    ├── 1.css
    └── 2.css

以上。教练我一天之内都不想写代码了。