Hugo themeのサブフォルダ対応が不十分な時

2025-12-06 Tech Akky

ブログをサブフォルダに置く

WordPress, Jekyll, Deno Lume, と使うたびに、サブフォルダにブログを作った時の挙動の怪しさに悩んで時間がとられているように思います。

多くのブログシステムで、

https://example.com/

のような場所にブログを置くことがデモやサンプルでは当たり前で、

https://blog.example.com/

サブドメインに置く場合は特に困ることもありません。

しかし、

https://example.com/blog/

に置こうとするとページやリンクの生成がおかしくなる。

Hugo では

今回、手っ取り早く(=カスタマイズ最小で)新ブログを作るために Hugo を試しているのですが、Hugoの場合、設定の toml ファイルで

baseURL = 'https://example.com/blog/

とすれば、おおむね行けそう、と最初は思いました。

しかし、theme を入れ替えて試すと、theme によってはナビゲーション(トップロゴからの / リンクとか)やサイト内リンク( tags/ とか)が /blog/ ではなく / から始まる本来のURLになってしまうことが多々起こりるようｄす。

これは、theme の中の HTML で、リンクを

<a class="navbar-brand" href="{{ "tags/" | relLangURL }}">{{ .Site.Title }}</a>

などと書けば問題ないのですが、

<a class="navbar-brand" href="{{ "/tags/" | relLangURL }}">{{ .Site.Title }}</a>

のようにルートから書くと発生してしまう(= baseURL のサブフォルダを考慮してくれなくなる)のが原因のよう。

対処として

theme をローカルで直す (問題のあるtemplates をコピーして、そちらを修正することで修正版で上書き動作させる)
theme 作者に伝えて直してもらう
canonifyURLs = true を指定する

があるようです。

canonifyURLs

これは、生成するURLを絶対パスに強制するもののようで、その時に baseURL を考慮してくれるため、リンクが “/” から始まっていても問題なく(=サブフォルダに置いた時のリンク先に)動くということのよう。

ただ、これはおおむね動く、でもバグとか特殊な条件では知らんよ、ということみたい。(by ChatGPT) 1も2も面倒さが多いので、とりあえず3かなあ。

余談 PHP/Symfony の static site generators

Symfony を触ってるんだから Sculpin で、と思ったけども、Sculpin もそこまで活発じゃない(最後のブログ更新が2019)しそうなるとモダンPHPでもない。

Stenopeはちょっと見た感じすごく面白そうだし新しいし、これでブログ作ると楽しそうなんだけど、これはSSGのためのキット的な感じで、ブログに限らず何でも作れるけども細々したところは各自頑張ってね、みたいなもののようで、ブログ作りを勉強したいわけじゃないからなあ。ヤクの毛刈りが始まってしまう、ということで一旦諦めました。