WordPressからHugoに移行した全記録｜90記事を2日で移行した方法と想定外の落とし穴
この記事は以下の記事の続編です。前回はWordPressでの運用の限界と、次の技術スタックとしてHugoを選んだ経緯を書きました。今回はその実際の移行作業の全記録です。
なぜWordPressをやめたのか
結論から言うと、WordPressの管理画面を一切開かなくなったからだ。
Claude Codeで記事を書き、REST APIで投稿し、SEO設定もAPIで済ませる。管理画面にログインする理由がない。なのにWordPressは毎月サーバー代を請求してくる。プラグインの更新通知が来る。セキュリティパッチを当てろと言ってくる。
使わない管理画面のために、管理コストだけ払っている状態。これが移行を決めた最大の理由だ。
テーマ選び：4つ試して全部微妙だった話
Hugoのテーマ選びは正直かなり苦労した。WordPressのCocoonが「インストールしたらそのまま使える」レベルだったのに対して、Hugoのテーマは「カスタマイズのベースにするもの」という思想の違いがある。
実際に試したテーマ:
- Stack — 左サイドバーのモダンなデザイン。悪くないが、サイドバーがスマホで完全に消える仕様がCocoonと違いすぎた
- Blowfish — 評判が良かったが、サイドバーがそもそもない。1カラムのミニマルデザインで、ブログとしてはちょっと物足りない
- Congo — インストールしかけたが、Blowfishと似た方向性だったので途中でやめた
- Mainroad — 最終的にこれに落ち着いた。Cocoonに近い2カラム構成で、サイドバーがスマホで下に回る伝統的なブログレイアウト
結局「モダンなデザイン」と「ブログとしての使いやすさ」は別物だった。見た目がおしゃれでも、読者が記事を読む導線が悪ければ意味がない。
CSSカスタマイズ：ここが一番時間かかった
テーマを選んだ後が本番だった。Mainroadのデフォルトデザインからcocoonの見た目に近づけるために、custom.cssが1100行を超えた。
やったこと:
- ヘッダー画像の全幅表示
- ナビバーのデザイン変更（紺背景→白背景+ホバーエフェクト）
- 記事カードのレイアウト（アイキャッチ+タイトル+説明文+メタ情報）
- サイドバーのウィジェットデザイン
- テーブルのスタイリング（Cocoon準拠の縞模様）
- ページネーションの丸ボタン化
- 目次のデザイン
- h2/h3の見出しスタイル
- レスポンシブ対応
一つ一つは大した作業じゃないが、「ちょっと違う」の積み重ねが膨大だった。色が微妙に違う、余白が多い、ホバーが効かない、スマホで崩れる。毎回CSSを書いて、リロードして、「あ、ここも直さなきゃ」の繰り返し。
ただ、Hugoの良いところはテーマのファイルを直接いじらないこと。layouts/ に同名ファイルを置けば上書きされるし、CSSも custom.css で追記するだけ。テーマのアップデートに影響されない設計は素直に良いと思った。
90記事の移行：スクリプト一発…とはいかなかった
WordPress REST APIから全記事を取得して、HTMLをMarkdownに変換するスクリプトを書いた。これ自体は30分で完成。実行も1分で90記事が変換された。
問題はここからだった。
CocoonのSEOメタデータが取れない
CocoonのSEOタイトルとメタディスクリプションは、REST APIのmetaフィールドに露出しない。Cocoon独自のカスタムフィールドで、UIの $_POST 経由でしか保存されない設計だった。
結局、全90ページをスクレイピングしてHTMLの <title> タグと og:description から取得した。REST APIがあるのにスクレイピングするという本末転倒な解決策。
テーブルが全滅
WordPressのHTMLテーブルをMarkdownに変換する際、ヘッダー行の区切り（| --- | --- |）が正しく生成されないケースが大量に発生。28記事のテーブルが壊れていた。
Markdownのテーブルは厳密で、ヘッダーの次の行に必ず --- が必要。HTMLからの自動変換では列数の検出やネストの処理が不完全で、手動修正が必要だった。
DALL·Eファイル名のエンコーディング問題
WordPressの画像ファイル名に DALL·E の中黒（·）が含まれているものが10件あり、Pythonの urllib がASCIIエンコードエラーで落ちた。URLエンコーディングを正しく処理するように修正して解決。
Cocoonブログカードの残骸
CocoonのブログカードはHTMLで出力されるが、Markdown変換するとこうなる:
[タイトル説明文www.morisakiblog.com日付](/slug/)
完全に壊れたMarkdown。これを全記事からスクリプトで検出して、Hugoのショートコードに置換する作業が発生した。
太字（**）が日本語で効かない
HugoのMarkdownパーサー（goldmark）は、日本語テキストと ** の間にスペースがないと太字として認識しないケースがある。英語前提で作られたパーサーの罠。結局 <strong> タグに置換して対応した。
検索機能：Pagefindが優秀すぎた
WordPressの検索はサーバーサイドでDB検索するが、静的サイトではそれができない。Pagefindという静的サイト用の検索エンジンを導入した。
仕組みは単純で、ビルド後のHTMLからインデックスファイルを生成し、ブラウザ上のJavaScriptで検索する。サーバーに問い合わせない。完全に無料。
導入はビルドステップに1行追加するだけ。検索結果のUIは自作する必要があったが、ホームの記事カードと同じデザインに合わせた。
人気記事：GA4 APIでビルド時に取得
サイドバーに人気記事を表示するために、GA4 APIからPVランキングを取得するスクリプトを書いた。
ポイントはgitの履歴を汚さない設計にしたこと。data/popular.json は .gitignore に入れて、GitHub Actionsのビルド時にGA4 APIから取得→JSON生成→Hugoビルドという流れ。リポジトリにはスクリプトとテンプレートだけが残る。
移行して感じたこと
速い。圧倒的に速い
WordPressは1ページ表示に約1秒かかっていた。Hugoは0.1秒。10倍速い。しかもサーバー代ゼロ。
管理が楽
記事もデザインもgitで管理。差分が見える、履歴が残る、ブランチで実験できる。WordPressの管理画面でポチポチやっていた作業が全部コードで完結する。
でもWordPressは悪くない
非エンジニアが「ブログ始めたい」となったら、今でもWordPress一択だと思う。管理画面があって、プラグインがあって、テーマがあって、コードを書かなくても形になる。
Hugoが合うのは、コードが書けて、CLIに抵抗がなくて、AIツールで自動化してる人。つまり限られた層。でもその層にとっては、WordPressに留まる理由がない。
WordPress vs Hugo 比較表
| 項目 | WordPress | Hugo |
|---|---|---|
| 表示速度 | 約1秒 | 約0.1秒 |
| サーバー代 | 月額数百〜千円 | 無料（GitHub Pages） |
| 記事管理 | 管理画面 | git + Markdown |
| デザイン自由度 | テーマ+プラグイン | CSS + テンプレート上書き |
| 移行コスト | — | 2日（90記事） |
| 向いてる人 | 非エンジニア | コード書ける人 |
Claude Codeなしでは無理だった
今回の移行で一番伝えたいのはこれかもしれない。この移行作業の9割はClaude Codeがやった。
具体的に何をやってもらったか:
- 移行スクリプトの作成・実行 — WP REST APIから全記事取得→HTML→Markdown変換→front matter生成→画像ダウンロード。スクリプト自体をClaude Codeが書いて、エラーが出たらその場で修正して再実行
- CSSカスタマイズ1100行 — 「Cocoonのこのデザインに合わせて」と言うだけで、ブラウザのスクショを見ながらCSSを書いてくれた。微調整も「もうちょい大きく」「色を薄く」で伝わる
- テンプレート上書き — summary.html、single.html、baseof.htmlなど、テーマのレイアウトを上書きするHTMLテンプレートを全部書いてくれた
- ショートコード作成 — blogcard、linkcard、画像グリッド（2x1, 2x2, 3x1, 3x2, 4x1）を全部作成
- Pagefind検索機能 — 導入からUIのカスタマイズまで
- GA4連携スクリプト — 人気記事ランキングのAPI取得スクリプト
- GitHub Actions — CI/CD、Dependabot、デプロイワークフロー
- リポジトリ設定 — ブランチ保護、スカッシュマージ限定、Secretsの登録まで全部
ghコマンドで - 壊れた記事の修正 — テーブル崩れ、引用崩れ、画像パス修正、ブログカード残骸の置換
自分がやったのは「どうしたいか」を伝えることと、ブラウザで見て「ここが違う」と指摘することだけ。デザインの方向性を決めるのは人間の仕事だが、それを実装するのはClaude Codeの方が圧倒的に速い。
正直、自分一人でやったら2週間はかかっていたと思う。それが2日で終わった。しかもCSSの細かい調整やスクリプトのデバッグは、人間がやるとストレスがたまる単純作業だ。それをClaude Codeが黙々とこなしてくれる。
エンジニアがAIツールを使う最大のメリットは「できることが増える」ではなく「面倒なことをやらなくて済む」だ。Hugo移行はまさにそれを実感した作業だった。
まとめ
移行作業は大変だったが、終わってみれば「もっと早くやればよかった」という感想しかない。
WordPress → Hugo移行を検討してる人へのアドバイス:
- テーマ選びで悩みすぎるな。結局CSSで全部変えるから、DOM構造とJSが合ってれば何でもいい
- URL構造だけは絶対に一致させろ。SEO評価がリセットされる
- 移行スクリプトで完璧は求めるな。8割自動化して残り2割は手動で直す方が速い
- Claude Codeを使え。マジで
