Hugoをやめる日に備えて、依存を本文・表示・ビルドの3層に分けた

WordPressからHugoへ移したとき、僕は次の移行で記事本文まで直す作業を避けたいと考えました。

記事本文は公開するたびに増えます。一方、テンプレートと設定は範囲が限られています。そこで、Hugoに依存している箇所を一覧にし、ブログを本文・表示・ビルドの3層に分けました。

この記事では、本文をHugo固有の記法から離し、表示とビルドへ依存を集めた設計を書きます。確認したのはHugo v0.164.0（2026年7月時点）です。

「Hugo移行記」のうち、移行後の設計を扱う記事です。先行記事を読まなくても、この記事だけで分かるように書いています。

まず全体像

静的サイトジェネレーターを乗り換えるとき、本文、テンプレート、設定では作り直す量が異なります。

テンプレートと設定は、移行先に合わせて書き直す対象です。記事本文は増え続けるため、ここまでツール固有の記法にすると、書き直す作業量が記事数に比例します。

この差から、本文にはHugo固有の記法を入れず、表示とビルドはHugoの機能を使う方針にしました。

本文の層に入るのは、記事とショートのMarkdownです。本文冒頭の設定欄であるfront matterと、ショートのスレッド区切りも、同じファイルに入ります。

ここで最初に決めたのは、Hugoのショートコードを使わないことでした。ショートコードを使うと、Hugoが処理する専用の呼び出しが記事本文に入るためです。

ショートへ追加投稿を足す仕組みでは、 というHTMLコメントを区切りにしました。

最初の投稿本文。

<!--thread-->

追加投稿の本文。

現在のテンプレートは、この文字列で本文を分割します。区切りコメントより後を追加投稿として表示する処理です。

別のツールへ移る場合は、同じ分割処理を実装する必要があります。区切り自体はMarkdownファイルにそのまま残ります。

front matterには title、date、slug、category、series、tag などを入れています。移行先でキー名や扱いが異なる場合は、対応付けが必要です。本文と設定欄を分けているため、記事の文章へ変換処理をかけずに済みます。

記事ごとのfront matterには draft フラグを書きません。公開状態はフォルダの場所で表し、公開するときは content/drafts/ から content/posts/<年>/ へフォルダごと移します。フォルダ全体を未公開にする処理は、ビルドの層へ置きました。

表示の層には、再利用するソースと書き直すテンプレートがあります。

デザインは assets/css/、動きは assets/js/ に置いています。どちらも変換処理を挟まないCSSとJavaScriptです。既製テーマも使っていません。

移行時はCSSとJavaScriptのソースを再利用できます。ただし、CSSが参照するクラス名やJavaScriptが操作するHTML構造は、移行先のテンプレートでも合わせる必要があります。

Hugoは、番号順にファイルを1つへまとめ、不要な空白を除いて圧縮します。さらに、内容から作る識別値をファイル名へ付けます。

これはブラウザへ渡すファイルを作る処理で、CSSとJavaScriptのソース自体は変更しません。移行先では同じ処理を組むか、ファイルを個別に読み込む形へ変えます。

ページのHTML構造を作る layouts/ は、Hugoのテンプレート構文で書いています。そのため、移行先に合わせて書き直します。デザインはここへ入れず、CSSへ分けています。

目次、前後の記事へのナビゲーション、関連記事も、Hugoが生成します。移行先に同じ機能がなければ省略できます。いずれも記事本文を書き換える理由にはなりません。

ビルドの層は、移行先に合わせて書き直す前提です。

サイト全体の設定ファイル hugo.toml には、URLの形式、分類3種類の定義、コードハイライト、関連記事の重み付けが入っています。URLの形式はWordPress時代と同じ /年/月/日/スラッグ/ を維持しているので、この一行だけは移行先でも必ず再現します。

[permalinks]
posts = '/:year/:month/:day/:slug/'
shorts = '/shorts/:year/:month/:day/:slug/'

未公開の記事をまとめて扱う設定も、この層です。content/drafts/_index.md の1か所で、配下の記事へ draft: true を引き継がせます。同じ設定で、draftsフォルダ自体もページや一覧へ出力しません。

移行先では、content/drafts/ を公開対象から外す設定または処理へ置き換えます。

ここまでの整理を1つの表にすると、次のようになります。

層	入っているもの	Hugoをやめたときの扱い
本文	記事とショートのMarkdown	本文を維持する
本文	front matter、`<!--thread-->`	キーの対応付けとスレッドの分割処理を用意する
表示	`assets/css`、`assets/js`	ソースを再利用し、必要ならHTML構造を合わせる
表示	`layouts/` のテンプレート、CSS/JSの配信用処理	移行先に合わせて書き直す
表示	目次、前後ナビ、関連記事	同等機能で再現する。なければ省略しても本文に影響しない
ビルド	`hugo.toml`（URL形式、分類、ハイライト、関連記事の重み）	新しいツールの設定で書き直す。URL形式だけは必ず再現する
ビルド	`drafts/_index.md` の一括未公開設定	「ビルド対象から外す」設定に置き換える

表に載っていないHugo固有の機能は、そのまま追加しないことにしました。必要になった場合は、使う前に表へ追記し、どの層へ置くかと移行時の扱いを決めます。

記事数に比例する書き直しを避けるため、本文にはHugo固有の記法を入れず、表示とビルドへツール固有の処理を置きました。依存表へ追記してから新しい機能を使う運用にすると、表と実装の差も確認できます。

実際に別のツールへ移す作業は、まだ試していません。本文、CSS、JavaScriptをどこまで再利用できるかは未検証です。