【Hugo】--printPathWarningsで出力パスの重複を検出する

実現したいこと

Hugoは複数のページが同じ出力先パスに解決される場合でも、既定では警告を出さない。後から書き込んだページが先に書き込んだページを黙って上書きするため、片方のページが公開されない不具合に気付きにくい。

--printPathWarningsを付けると、出力先パスが重複しているページをビルド時の警告として表示できる。

使い方

$ hugo --printPathWarnings

動作確認

urlのfrontmatterで意図せず同じ出力先パスを指定してしまった例で確認する。

# content/post-a/index.md
---
title: "PostA"
url: "/same-path/"
---

# content/post-b/index.md
---
title: "PostB"
url: "/same-path/"
---

--printPathWarningsを付けずにビルドすると、警告なしで終了する。

$ hugo
Start building sites …
...
Total in 9 ms

生成された/same-path/index.htmlの中身はPostAとPostBのどちらか一方だけで、もう片方の内容はビルドの過程で黙って上書きされて消えている。ページは並行してレンダリングされるため、どちらが残るかは実行するたびに変わりうる。

--printPathWarningsを付けると、重複が警告として表示される。

$ hugo --printPathWarnings
Start building sites …

WARN  Duplicate target paths: /same-path/index.html (2)
...
Total in 8 ms

どちらの実行もビルド自体は正常終了(終了ステータス0)として扱われる。--printPathWarningsを付けなければ、この重複はビルドログのどこにも現れない。

CIでビルドを失敗させる

--panicOnWarningと組み合わせると、警告発生時にビルドを異常終了させられる。

$ hugo --printPathWarnings --panicOnWarning
...
WARN  Duplicate target paths: /same-path/index.html (2)
Total in 9 ms
panic: Duplicate target paths: /same-path/index.html (2)
...
$ echo $?
2

panicによるスタックトレースは読みにくい。それでも終了ステータスは0以外になる。CIのビルドステップに--printPathWarnings --panicOnWarningを加えておけば、出力パスの重複をコンテンツの見落としではなくビルド失敗として検出できる。

参考: hugo | Hugo