今天要解的問題

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

navi-split 那篇的健診頁截圖撐滿 960px 欄寬,圖裡的「健診」「該整理一下」比上方的內文字還大
改動前的健診頁截圖

這件事我前後開了三張 issue 卡著:有些圖片太大;圖片固定滿寬,本來就小的圖反而被迫放很大;還有想在圖片下方固定放 caption,讓讀者知道圖片在講什麼。三張要改的都是同一個圖片輸出的範本,所以併起來一起做。

改完之後,同一張截圖顯示成 643px 寬、置中,圖裡的字跟內文差不多大:

同一張健診頁截圖縮成 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](images/x.png "caption")。那時我想說,這樣 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: ![alt](images/x.png "短的名詞片語")'
  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 會被擋下。