【Hugo】hugo convert toYAMLでfrontmatterをYAMLへ揃える

実現したいこと

記事ごとにfrontmatterの引用符の付け方やキーの並び順がばらついていても、hugoは特に気にせずビルドする。統一されていなくても動くからこそ、後から手作業で揃えるのは手間である。

hugo convert toYAMLを使うと、content/配下すべての記事のfrontmatterをYAML形式に揃えて書き出せる。

-o(--output)で書き出し先を指定して実行する。

$ hugo convert toYAML -o /tmp/hugo-convert-out

-oと--unsafeのいずれも付けずに実行すると、安全のため変換されずエラーになる。

$ hugo convert toYAML

Error: command error: Unsafe operation not allowed, use --unsafe or set a different output path

content/を直接上書きするコマンドであるため、まず-oで別ディレクトリに出力して結果を確認するのがよい。

このブログの記事で試すと、frontmatterのキーがアルファベット順に並べ替えられ、引用符の付け方も統一される。

# 変換前
title: "Convert to Yaml"
date: 2026-09-13T03:57:28+09:00
toc: true
thumbnail: img/thumbnail.png

# 変換後
date: "2026-09-13T03:57:28+09:00"
thumbnail: img/thumbnail.png
title: Convert to Yaml
toc: true

dateは引用符なし→引用符付きに、titleは引用符付き→引用符なしに変わり、キーはdate, thumbnail, title, tocの順になった。

titleから一律に引用符が外れるわけではない。値にコロンを含む記事で試すと、引用符は外れずシングルクォートに変わる。

# 変換前
title: "【Terraform】Error putting S3 policy: AccessDenied: Access Deniedの対処法"

# 変換後
title: '【Terraform】Error putting S3 policy: AccessDenied: Access Deniedの対処法'

コロンに続けて空白があるとYAMLのマッピングと区別できなくなるため、引用符なしにはできない。値にダブルクォートを含む記事も同様にシングルクォートへ変わる。

# 変換前
title: "【Terraform】\"Principal\": \"*\" を指定する方法"

# 変換後
title: '【Terraform】"Principal": "*" を指定する方法'

ダブルクォートをエスケープする代わりにシングルクォートで囲むことで、バックスラッシュによるエスケープを避けている。値ごとにYAMLとして安全な表現を選んで引用符を付け替えており、一律に外したり付けたりしているわけではない。

-oを付けずにcontent/を直接書き換えるには--unsafeを付ける。

$ hugo convert toYAML --unsafe

フロントマターの書式だけが変わり、本文は変更されない。ただし対象はcontent/配下の全記事であり、書式の違いだけで数百ファイル規模の差分が生じる。実行する場合は事前にコミットしておき、差分を確認してから反映する。