Hugo から Astro への移行

Hugo ユーザーが Astro に移行する理由

Hugo は高速です。信じられないほど高速です。数千ページを 1 秒以下でビルド、依存関係なし、単一バイナリ。純粋なビルド速度が唯一の指標なら、Hugo が勝ちます。

しかし、開発者が Hugo を離れる理由はビルド速度ではありません。Go テンプレートが原因です。

すべての Hugo ユーザーがこの壁に直面します：レイアウト内に条件付きロジックが必要になり、Go テンプレートのドキュメントを開くと、{{ with .Params.subtitle }} が期待どおりに動作しない理由に 45 分が消えます。JavaScript エコシステムに住んでいる人にとって、この構文は異質です。Partial はぎこちなく感じます。Shortcode は回避策に見えます。Hugo の組み込みパイプを超える機能が必要になると、ほとんどのフロントエンド開発者が触らない Go を書くことになります。

Astro は Hugo の価値を保ちます — Markdown ファースト なコンテンツ、静的出力、高速パフォーマンス — そしてイライラする部分を最新のコンポーネントモデル、npm エコシステム、JSX のような構文に置き換えます。

Astro に Hugo サイトを数十個移行してきました。実際のプロセスはこのような感じです。

移行を推進する問題点

Go テンプレートは JavaScript 開発者にとって行き止まり

Hugo のテンプレート言語は強力ですが、不透明です。コンテンツのソート、フィルタリング、条件付きレンダリングには、Hugo 特有の関数（range、where、with、partial）を覚える必要があり、スタックの他の場所には転送されません。数ヶ月後に Hugo プロジェクトに戻ると、基本的に最初からやり直しです。

Astro コンポーネントは .astro ファイルで JSX のような構文を使います。React、Vue、Svelte を書いたことがあれば、必要な知識の 90% は既に知っています。学習曲線は週ではなく、時間単位です。

npm エコシステムへのアクセスがない

構文ハイライトが必要ですか？Hugo には Chroma が組み込まれており、それは素晴らしいです。他に何か必要ですか？基本的に自分で対処する必要があります。Hugo の拡張モデルは shortcode、partial、Go モジュールに限定されており、npm install に相当するものはありません。コンポーネントライブラリはありません。チャートライブラリ、検索統合、カスタムウィジェットを取り込む簡単な方法はありません。

Astro は Node.js の上に構築されています。npm レジストリ全体がそこにあります。読了時間計算機が必要ですか？npm install reading-time。RSS フィードが必要ですか？@astrojs/rss。全文検索が必要ですか？Pagefind は数分で統合できます。エコシステムアクセスの違いは誇張しすぎるほどではありません。

Shortcode とコンポーネント

Hugo shortcode は文字列ベースのテンプレート包含で、合成可能性が限定的です。複雑なデータ構造を渡すことはできません。信頼できるようにネストすることはできません。型チェックすることはできません。

Astro コンポーネントは実際のコンポーネントです。型付きプロップを受け入れ、任意にネストでき、スロットをサポートし、他のコンポーネントをインポートできます。Hugo shortcode を Astro コンポーネントに変換すると、テスト可能性、再利用可能性、IDE オートコンプリートが得られます — shortcode が与えられないもの。

限定的なデータ取得

Hugo はローカルの JSON、YAML、TOML ファイルを getJSON またはデータテンプレート経由でプルできますが、ビルド時に外部 API からフェッチするのは厄介です。ミドルウェア概念、サーバーエンドポイント、ハイブリッドレンダリングはありません。

Astro は標準 fetch() を使用したビルド時データ取得、動的ルートのオプションサーバー側レンダリング、API エンドポイント — すべて同じプロジェクト内で処理します。静的サイトが 1 ～ 2 ページの動的ページが必要な場合、Astro は別のバックエンドをボルトで留めずに処理します。

Astro で得られるもの

型安全性を備えた Content Collections

Astro の Content Collections API は Zod を使用して Markdown frontmatter のスキーマを定義できます。すべてのブログ投稿、ドキュメントページ、製品エントリはビルド時に検証されます。date フィールドがない投稿を追加するか、形式が正しくない tags 配列があると、ビルドが明確なエラーで失敗します。Hugo にはこのようなものはありません。

フレームワークの柔軟性

Astro の island アーキテクチャを使用すると、静的ページ内に React、Svelte、Vue、Solid、Preact コンポーネントを使用でき、デフォルトではゼロ JavaScript が送信されます。対話的なコンポーネントのみが hydrate されます。100% 静的 HTML のドキュメントサイトを構築でき、React が必要な場合にのみロードされる単一の対話的検索ウィジェットがあります。

最新のアセットパイプライン

Astro は Vite を利用します。開発中にホットモジュール交換、astro:assets 経由の最適化された画像処理、コンポーネントごとの自動 CSS スコーピング、ツリーシェイク JavaScript バンドルが得られます。Hugo Pipes は機能しますが、既にジャグリングしている他のすべての Hugo 固有 API の上にもう 1 つあります。

ビュー遷移

Astro は JavaScript フレームワークなしで、SPA のようなページナビゲーションを静的サイトに与える組み込みビュー遷移を提供します。ページはルート間をスムーズにモーフィングします。Hugo には相当するものはありません — Turbo または barba.js のようなものを自分で配線する必要があります。

Hugo から Astro への移行プロセス

フェーズ 1：コンテンツ監査とマッピング（1 週目）

Hugo プロジェクトのすべてのコンテンツタイプ、タクソノミ、shortcode、partial をインベントリします。Markdown ファイルは frontmatter 構造、shortcode 使用法、コンテンツに埋め込まれた Hugo 固有テンプレート関数について分析されます。各 Hugo コンテンツタイプは型付きスキーマを持つ Astro Content Collection にマップされます。

フェーズ 2：コンテンツ転送（1 ～ 2 週目）

Markdown はきれいに転送されます — これは 2 つの Markdown ファースト フレームワーク間を移動する最大の構造的利点です。YAML frontmatter は Astro では同じように機能します。TOML frontmatter は YAML に変換する必要があり、自動化します。JSON frontmatter も変換する必要がありますが、簡単です。

Shortcode はほとんどの作業が発生する場所です。各 Hugo shortcode は Astro コンポーネントに書き直され、shortcode を使用するコンテンツファイルは .md から .mdx に変換され、コンポーネントをインポートして使用できます。同じ shortcode を使用する数百の投稿があるサイトの場合、ファイルを 1 つずつ編集するのではなく、カスタム Remark プラグインを作成して自動的に変換を処理します。

フェーズ 3：テンプレート再構築（2 ～ 3 週目）

Go テンプレートは完全に書き直されます — パラダイムが異なるすぎるため、自動コンバーターはありません。すべての baseof.html、list.html、single.html、partial は Astro レイアウトまたはコンポーネントになります。ここが DX の改善が本当に実感される場所です。新しいテンプレートはより短く、読みやすく、JavaScript を知っている誰もが保守できます。

デザインシステムを Tailwind CSS または既存 CSS フレームワークでスコープされた Astro コンポーネントとして再構築します。すべてのコンポーネントはドキュメント化され、明確なファイル構造で整理されます。

フェーズ 4：機能パリティと強化（3 ～ 4 週目）

Hugo 固有の機能をレプリケートします：タクソノミページ、RSS フィード、サイトマップ、ページネーション、関連投稿、該当する場合は多言語対応。次に、Hugo が簡単にできなかったことを追加します — Pagefind を使用したクライアント側検索、astro:assets による最適化された画像処理、ビュー遷移、およびサイトが必要とするどのような対話的機能。

フェーズ 5：SEO 保持とローンチ（4 ～ 5 週目）

これは交渉の余地がありません。すべてのインデックス URL は移行後に正しく解決する必要があります。

SEO 保持戦略

Hugo と Astro は URL 生成を異なる方法で処理します。Hugo はコンテンツディレクトリ構造と slug/url frontmatter を使用します。Astro は src/pages/ のファイルベースルーティングを使用するか、Content Collections から getStaticPaths() 経由でページを生成します。

移行プロセスはすべてをカバーします：

• 完全な URL マッピング：既存サイトをクロールして、すべての URL を同等の Astro にマップします
• リダイレクト設定：URL 構造の変更は、ホスティングレベル（Vercel、Netlify、Cloudflare）で 301 リダイレクトとして設定されます
• Canonical タグ検証：すべてのページが正しい canonical URL を取得します
• 構造化データ移行：JSON-LD スキーマは転送され、検証されます
• サイトマップ生成：Astro の @astrojs/sitemap 統合は正確なサイトマップを生成します
• メタタグ監査：タイトルタグ、説明、Open Graph タグはページごとに検証されます
• 内部リンク検証：移行後、すべての内部リンクをテストして、リンク切れを引っかかるようにします

起動後 60 日間 Search Console を監視して、インデックスの問題を早期に引っかかります。

タイムラインと価格

典型的な Hugo から Astro への移行は、サイトの複雑さに応じて 4 ～ 6 週間実行されます：

• 小規模サイト（50 ページ未満、シンプルなブログ）：3 ～ 4 週間、$6,000 から
• 中規模サイト（50 ～ 500 ページ、複数のコンテンツタイプ、カスタム shortcode）：4 ～ 6 週間、$12,000 から
• 大規模サイト（500+ ページ、多言語、複雑なタクソノミ）：6 ～ 8 週間、$20,000 から

コンテンツ量はその他の何よりもタイムラインに影響します。1,000 投稿があるが単純なテンプレートのサイトは、50 ページ、15 個のカスタム shortcode、複雑なレイアウトロジックのあるサイトよりも移行が高速です。

この移行は自分に適していますか？

Go テンプレートと戦うのに疲れた JavaScript 開発者なら移行してください。npm パッケージ、対話的な island、またはハイブリッドレンダリングが必要なら移行してください。型安全なコンテンツスキーマと、他のすべてをビルドする方法と一致するコンポーネントモデルが必要なら移行してください。

Hugo のビルド速度がミッション実行時に極めて重要で、10,000+ ページをプッシュしている場合は移行しないでください — Hugo はその規模で生ビルドパフォーマンスで依然として勝利します。チームが Go をよく知っていて、テンプレート化モデルに満足している場合は移行しないでください。

他のすべての人：Astro は Hugo ユーザーが待っていたアップグレードです。同じ哲学、最新のツール、より優れた DX。