Hugo をバージョンアップしました

当サイトは静的サイトジェネレーターの Hugo を利用しています。

通常ブログを書いていて困ることはほとんどなく、 Hugo 本体のアップグレードについてはそれほど追いかけていない、という状態です。

今回は欲しい機能が出てきため、アップグレードを行いましたが、結果ハマりました。


アップグレード手順については次をご覧ください。

[Hugo] Homebrew で Hugo をアップグレードする
Hugo本体のバージョンアップ方法をご紹介いたします。
Atuweb 開発 Log

おことわり

バージョンアップは 2020年 2月 頃に行ったもののため、当記事でインストールしたバージョンと、記事公開次点の最新バージョンに差が出てしまいました。

また、カテゴリの作り方や、経由してきたバージョンによって、サイトの状態に違いがあると思います。

そのため、この記事に記載したエラーは出ない、エラーが解消しないという方もいらっしゃると思いますが、ご容赦ください。

アップグレードでやった対処について

記事一覧がリストが出ない

フロントページやタクソノミーの一覧で表示される記事が変になってしまいました。

雑に言うと

.Data.Pages -> .RegularPages なのですが、

.RegularPages.IsHome かどうかで挙動が違ってくるようで、難しいですね。

試行錯誤の結果、 list.html は次のようにしました。

1{{ $.Scratch.Set "pages" "" }}
2{{ if .IsHome }}
3{{ $.Scratch.Set "pages" .Site.RegularPages }}
4{{ else }}
5{{ $.Scratch.Set "pages" .RegularPages }}
6{{ end }}
7{{ $pages := $.Scratch.Get "pages" }}
8{{ $paginator := .Paginate $pages }}

Scratch を使って出し分けるようにしています。

[Hugo] Scratch を使ってみた
Hugoテンプレートを開発する場合、ブロックをまたいだ変数を扱うことができるScratchを知っておくと強くなれます。
Atuweb 開発 Log

調整中にビルドがものすごく遅くなってしまって困惑したのですが、ビルド結果を見ると Paginator pages が 15,000 ページと大量に生成されていた、ということがあり原因はここでした。

デフォルトの list.html をミスるとこうなるためご注意ください。

ショートコードや IFRAME タグがでない

お問い合わせページなど、一部のコンテンツが出なくなっていて、 HTML ソースをチェックするとこんなコメントがでていました。

1<!-- raw HTML omitted -->

これは、 v0.60.0 に行われた変更の影響で、

  • Markdown に HTML はふつう書かないよね
  • デフォルト OFF にするよ
  • HTML をゴリゴリ書きたい場合は unsefe を宣言してね

というものです。

Hugo
Now CommonMark Compliant!
https://gohugo.io/news/0.60.0-relnotes/

対処方法としては config.toml に次を追加します。

1[markup.goldmark.renderer]
2unsafe = true

上記の設定を入れなくても、ショートコード化で逃げる事ができるものもあります。

ショートコードは 2 種類の書き方があり

{{% shortcode %}} は HTML が無効化され

{{< shortcode >}} だと HTML として解釈してくれるようでした。

公式のショートコードページでは、この挙動の違いに対する説明を見つけられませんでした。

カテゴリ階層の変化

/ が入っているカテゴリ (タクソノミー) の扱いが変わったようです。

Hoge/Fuga というカテゴリを作った場合、

今までは
hoge_fuga というパスになっていましたが、

hoge/fuga というように階層構造として扱ってくれます。

これは、 URL も変わってしまう強い副作用 のある変更です。
URL が変わるのはキツイです。

内部リンクは良いとして、外部からのリンクは制御しきれませんから、そのままですと 404 エラーが多発します。

対処として、 .htaccess にリダイレクトを貼りました。

devops というカテゴリだけ、階層構造にしているため、 .htaccess

1RedirectMatch permanent ^/categories/devops-(.*)/(.*)$ https://atuweb.net/categories/devops/$1/$2

というようにしました。


また、リストページの挙動にも特徴があり、

カテゴリを hoge/fuga にしたページは

  • カテゴリ hoge の一覧
  • カテゴリ hoge/fuga の一覧

両方に含まれる、

ただし、親となるカテゴリ hoge のみを設定したページがゼロの場合、 hoge カテゴリ一覧が生成されない、というクセがあるようでした。

TOC の深さが変わった

従来は ULタグ が一つ余計についていましたが、正常に戻ったようです。

私は ULタグ のネスト数で CSS を調整しているところがあって、そこだけ修正が必要でした。

JSON ファイルが読めない ?

1{{ $jsonPath := (printf "/data/asin/%s.json" $asin) }}
2{{ if (fileExists $jsonPath) -}}
3{{ end }}

上記のコードで、JSON ファイルを参照できない、という症状が発生するようになりました。
パスは合っているはずなのにです。


調べてみると、引数 $asin が数値のみの場合に機能しなくなっていることがわかり、今まで暗黙にキャストしてくれていたんだなーということを知った感じです。

対処としては、素直にキャストを足しました。

1<!-- 修正後 -->
2{{ $jsonPath := (printf "/data/asin/%s.json" (string $asin)) }}

Deprecated

Deprecated (非推奨) もいくつかあり、書き換えを行いました。

Deprecated はメッセージを出してくれて、すぐに対処ができました。

Page.Hugo is deprecated

1WARN 2020/03/01 00:00:00 Page.Hugo is deprecated and will be removed in a future release. Use the global hugo function.

Page.Hugo はそのうち消すから hugo function を使うようにしてね。

1<!-- 修正前 -->
2{{ .Hugo.Generator }}
1<!-- 修正後 -->
2{{ hugo.Generator }}
1WARN 2020/03/01 00:00:00 Page.RSSLink is deprecated and will be removed in a future release. Use the Output Format's link, e.g. something like:
2    {{ with .OutputFormats.Get "RSS" }}{{ .RelPermalink }}{{ end }}
1<!-- 修正前 -->
2{{ with .RSSLink }}<link rel="alternate" type="application/rss+xml" title="RSS" href="{{ . }}">{{ end }}
1<!-- 修正後 -->
2{{ with .OutputFormats.Get "RSS" }}<link rel="alternate" type="application/rss+xml" title="RSS" href="{{ .RelPermalink }}">{{ end }}

Page.IsDraft

1WARN 2020/03/01 00:00:00 Page.IsDraft is deprecated and will be removed in a future release. Use .Draft.
1<!-- 修正前 -->
2{{ if .IsDraft }}<li class="dev">D</li>{{ end }}
1<!-- 修正後 -->
2{{ if .Draft }}<li class="dev">D</li>{{ end }}

今回のグレードアップはけっこう手間がかかり、まとめてやると大変でした。

個人ブログみたいなものでも、最初からしっかりと開発ブランチを切って着手すればよかったな、と反省しました。