今天要解的問題
kiwi-walk 的內文圖片原本幾乎每張都撐滿內容欄,也就是 960px。照片這樣放沒問題,但截圖本來就不大,被放大之後,圖裡的字反而比旁邊的內文還大。像替兩個 navi 分工那篇的健診頁截圖,圖裡的字明顯比上面那行內文還大,高度也超過一個畫面。

這件事我前後開了三張 issue 卡著:有些圖片太大;圖片固定滿寬,本來就小的圖反而被迫放很大;還有想在圖片下方固定放 caption,讓讀者知道圖片在講什麼。三張要改的都是同一個圖片輸出的範本,所以併起來一起做。
改完之後,同一張截圖顯示成 643px 寬、置中,圖裡的字跟內文差不多大:

技術背景
Hugo 的 Markdown 圖片可以用 render hook(layouts/_default/_markup/render-image.html)自己決定輸出的 HTML。要讓它能做尺寸和 caption,hugo.yml 要開兩個 goldmark 的設定:
wrapStandAloneImageWithinParagraph: false:獨立一行的圖片不再包在<p>裡,hook 才能輸出<figure>。attribute.block: true:圖片下一行的{size=70}會進到 hook 的.Attributes。
這裡有個限制:{width=70%} 這種帶百分號的寫法 Hugo 不會解析,那一行會直接變成一段內文。
另外,自動預設要分辨照片和截圖,靠的是檔案是有損還是無損。JPEG 和 PNG 看檔案類型就知道,WebP 則要看檔頭:無損的 WebP 在檔頭會有 VP8L,有損的是 VP8 。
想法與取捨
一開始我只知道兩件事:「大小不知道怎樣調整比較好」,以及圖要「置中」。但「什麼叫太大」說不清楚,就沒辦法定規則。後來我給的判準是「圖片字體大小比內文字還大的時候」,這句就變成整個功能的主軸:
- 圖片裡的字不應該比內文字大。
自動縮到實際大小,還是讓我自己選
照上面的主軸,截圖和圖表是以 2× 繪製的,所以「實際大小」就是像素的一半。照這個規則自動縮,大部分截圖的字就會跟內文差不多。
但這樣有機會圖片太小,所以我想要的是像 Medium 那樣有 50、70、100 的選項,自動的不對時可以自己指定。寫法上,width 沒有比例的感覺,所以寫成 {size=70},數字是佔內容欄的百分比。
而圖不對的時候要怎麼跟 AI 講是哪一張,就靠 caption:我發現有圖片不符合時,可以用 caption 指出是哪一張。
caption 寫在 Markdown 的 title
caption 寫在 Markdown 圖片網址後面的引號裡:。那時我想說,這樣 alt 還會存在嗎?答案是會:alt 留給螢幕閱讀器,title 是顯示在圖下的字。
以前的文章可以忽略 caption,不需要補齊,之後的需要。要保證之後的圖一定有,我想到的是用 hook,所以 commit 前會擋下沒有 caption 的新圖。
照片不受高度上限
為了不讓一張截圖超過一個畫面,所有圖片的高度都設了不超過視窗的 85%。但這條和「照片寬度跟以前一樣」都是我同意過的規則,交集卻沒被預見:一張 4:3 的照片在 800px 高的視窗會被縮成 907px 寬,不再是原本的 960px。
這兩條只能留一條,我的決定是照片不要限制,高度上限只留給截圖。
實作
render hook:讀像素、決定寬度的規則
hook 在建置時讀每張圖的像素尺寸和有損/無損,再決定這張圖走哪一條寬度規則(data-fit)。CDN 上的圖用 resources.GetRemote 抓,跟封面圖的做法一樣:
{{- if $res -}}
{{- $sub := $res.MediaType.SubType -}}
{{- if in (slice "jpeg" "png" "webp" "gif") $sub -}}
{{- $nw = $res.Width -}}
{{- $nh = $res.Height -}}
{{- if eq $sub "png" -}}
{{- $lossless = true -}}
{{- else if eq $sub "webp" -}}
{{- $head := substr $res.Content 0 64 -}}
{{- $lossless = or (strings.Contains $head "VP8L") (and (strings.Contains $head "VP8X") (strings.Contains $res.Content "VP8L")) -}}
{{- $photo = not $lossless -}}
{{- else if eq $sub "jpeg" -}}
{{- $photo = true -}}
{{- end -}}
{{- end -}}
{{- end -}}
$photo 只有 JPEG 和有損 WebP 會是 true,後面拿掉照片的高度上限就靠它。
寬度的規則先看有沒有寫 size,50、70、100 以外的值會在建置時出警告,再退回自動:
{{- $fit := "unknown" -}}
{{- with .Attributes.size -}}
{{- $size := string . -}}
{{- if in (slice "50" "70" "100") $size -}}
{{- $fit = $size -}}
{{- else -}}
{{- warnf "render-image: {size=%s} on %s in %s is not 50, 70 or 100; using the automatic size" $size $src $where -}}
{{- end -}}
{{- end -}}
{{- if and (eq $fit "unknown") (gt $nw 0) -}}
{{- $fit = cond $lossless "shot" "photo" -}}
{{- end -}}
讀到的像素寫成 <figure> 上的 CSS 變數:--nw 是像素寬、--ar 是寬高比,截圖另外有 --w,就是像素寬的一半。caption 放在 <figcaption>,沒有 title 的圖就不會有這個元素:
<figure class="post-figure" data-fit="{{ $fit }}"{{ if $photo }} data-photo{{ end }}{{ with $style }} style="{{ . | safeCSS }}"{{ else }} data-nosize{{ end }}>
<img loading="lazy" src="{{ $src }}" alt="{{ $alt }}"{{ if gt $nw 0 }} width="{{ $nw }}" height="{{ $nh }}"{{ end }}>
{{- with $caption }}
<figcaption>{{ . }}</figcaption>
{{- end }}
</figure>
alt 是空的而有 caption 時,$alt 會用 caption 的文字。
CSS:寬度交給 min()
真正的寬度在 custom.css 的「Post figures」算,769px 以上才生效,768px 以下跟以前一樣是欄寬:
@media (min-width: 769px) {
.post-content .post-figure {
--cap: calc(85vh * var(--ar));
margin-left: auto;
margin-right: auto;
width: min(100%, var(--nw), var(--cap));
}
/* A photo (JPEG, lossy WebP) is never shrunk to fit the screen's height. */
.post-content .post-figure[data-photo] {
--cap: 100%;
}
.post-content .post-figure[data-fit="shot"] {
width: min(100%, var(--nw), max(50%, var(--w)), var(--cap));
}
.post-content .post-figure[data-fit="70"] {
width: min(70%, var(--nw), var(--cap));
}
/* ... */
}
每條規則都多帶兩個上限:var(--nw) 讓圖不放大超過自己的像素,--cap 是 85% 視窗高度換算成的寬度。照片的 --cap 設成 100%,等於沒有高度上限。截圖則是像素的一半,但至少半欄。比欄窄的圖用 margin: auto 置中。
寬度放在 <figure> 上,caption 就會在圖的寬度內換行。量出來的結果:
{size=50}、{size=70}、{size=100}在 960px 的欄是 480、672、960px。- 《博物臺灣》那篇 1400×1050 的照片顯示成 960×720,跟改動前一樣。
- 375px 寬時,圖片是 347px,頁面不會左右捲動。
- 全站 415 張內文圖片都走這套規則,讀不到尺寸的維持原本滿寬的行為。
pre-commit:新圖一定要有 caption
scripts/check-image-captions.sh 由 pre-commit 呼叫,只看這次 commit 在 content/blogs/ 底下新增的行。獨立一行的圖片沒有 title 就擋下,列出檔案和行號:
if [ -n "$hits" ]; then
printf '\033[31m%s\033[0m\n' "[pre-commit] BLOCKED: new post image(s) without a caption"
printf '%s' "$hits"
echo 'Add one as the title: '
echo "Bypass once with: ALLOW_NO_CAPTION=1 git commit ..."
exit 1
fi
因為只看新增的行,舊文章的圖不受影響。只改 alt 或只改路徑的舊圖(例如換成新的 CDN 網址)算編輯,不算新圖:同一段 diff 裡刪掉一張 alt 相同或路徑相同、沒有 caption 的圖,就放行。
踩到的坑
PaperMod 本來就有圖片 render hook
PaperMod 自己就有一個圖片 render hook,負責 lazy loading,以及把相對路徑解析成資源的網址。站上自己的 hook 會蓋掉它,所以這些行為要搬過來:
{{- /* Same src handling as PaperMod's hook, which this file replaces: a
relative path that names a page or global resource becomes its URL. */ -}}
{{- $u := urls.Parse .Destination -}}
{{- $src := $u.String -}}
{{- if not $u.IsAbs -}}
{{- $path := strings.TrimPrefix "./" $u.Path -}}
{{- with or (.PageInner.Resources.Get $path) (resources.Get $path) -}}
{{- $src = .RelPermalink -}}
{{- /* ... */ -}}
{{- end -}}
{{- end -}}
深色模式的 caption 顏色沒變
caption 用的是 --secondary 這個顏色變數,切到深色模式卻還是淺色的值。原因是 .post-single:not(.dark) 在文章上重新宣告了淺色的顏色變數,所以 --secondary 在文章裡不會變深。解法是把深色值直接寫出來:
body.dark .post-content .post-figure > figcaption {
color: #B8A77F; /* --ink-soft-warm (dark) */
}
macOS 的 awk 吃掉反斜線
caption 檢查用 awk 比對圖片那一行,一開始用 -v 把正規表示式傳進 awk。但在 macOS 的 awk 上,-v 會把值裡的反斜線吃掉,結果 hook 什麼都沒擋到;值裡有換行時還會直接報錯(newline in string)。後來改成用環境變數傳,在 awk 裡用 ENVIRON 讀:
# The two patterns reach awk through the environment: awk -v would eat their
# backslashes. \047 is a single quote.
export CAPTION_RE_IMAGE='^ ? ? ?!\[[^]]*\]\(.*\)[ \t]*$'
export CAPTION_RE_TITLED='[ \t]("([^"\\]|\\.)+"|\047([^\047\\]|\\.)+\047)[ \t]*\)[ \t]*$'
changes=$(git -c core.quotepath=off diff --cached -M -U0 --diff-filter=ACMR -- content/blogs | awk '
BEGIN { image = ENVIRON["CAPTION_RE_IMAGE"]; titled = ENVIRON["CAPTION_RE_TITLED"] }
# ...
建置變慢
hook 要在建置時抓每張圖讀尺寸,冷建置從約 2 秒變成約 40 秒。
GIF 被當成照片
拿掉照片的高度上限時,程式判斷的是「不是無損」就算照片。但 GIF 不是無損,也不是照片。一張 1200×1120 的文字 GIF 因此從 729px 寬變成 960px 寬、896px 高,超過一個畫面。重讀一次改動才發現,改成只有 JPEG 和有損 WebP 算照片,也就是上面的 $photo,GIF 照樣撐滿欄寬,但保留高度上限。
小結
現在內文圖片照「圖片裡的字不比內文大」決定寬度:
- 寫了 size:圖片下一行寫
{size=50}、{size=70}或{size=100},就是內容欄的比例。 - 照片:沒寫 size 時撐滿欄寬,沒有高度上限。
- 截圖、圖表:沒寫 size 時顯示成像素的一半,至少半欄,高度不超過視窗的 85%。
caption 寫在 Markdown 圖片的 title,顯示在圖下、跟圖一樣寬;舊圖不補,新圖沒有 caption 的話 commit 會被擋下。
