hugo

Hugo 静的サイトジェネレーター

ステータス: 本番環境で利用可能 | 最終更新日: 2026-08-03 最新バージョン: [email protected]+extended | ビルド速度: <100ms

---

クイックスタート（5 分）

1. Hugo Extended をインストールする

重要: SCSS／Sass のサポートが不要だと確信できる場合を除き、必ず Hugo Extended エディションをインストールしてください（Standard ではありません）。ほとんどのテーマで Extended が必要です。

# macOS
brew install hugo

# Linux (Ubuntu/Debian)
wget https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.deb
sudo dpkg -i hugo_extended_0.164.0_linux-amd64.deb

# Verify Extended edition
hugo version  # Should show "+extended"

重要な理由:

• Hugo Extended には SCSS／Sass の処理機能が含まれています
• 人気のテーマのほとんど（PaperMod、Academic、Docsy）では Extended が必要です
• Standard エディションでは「SCSS support not enabled」エラーが発生します
• Extended にデメリットはありません（速度と機能は同じで、さらに機能が追加されています）

2. 新しい Hugo サイトを作成する

# Use YAML format (not TOML) for better CMS compatibility
hugo new site my-blog --format yaml

# Initialize Git
cd my-blog
git init

# Add PaperMod theme (recommended for blogs)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

重要:

• hugo.yaml を作成するには --format yaml を使用してください（hugo.toml ではありません）
• Sveltia CMS では YAML が必須で、TinaCMS でも推奨されています
• Sveltia CMS ベータ版では TOML に既知のバグがあります
• 後でクローンする際、Git サブモジュールには --recursive フラグが必要です

3. 設定してビルドする

# hugo.yaml - Minimal working configuration
baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
enableRobotsTXT: true

params:
  ShowReadingTime: true
  ShowShareButtons: true
  defaultTheme: auto  # Supports dark/light/auto

# Create first post
hugo new content posts/first-post.md

# Run development server (with live reload)
hugo server

# Build for production
hugo --minify

# Output is in public/ directory

---

重要なルール

必ず行うこと

✅ Hugo Extended をインストールする（Standard ではありません）- テーマで SCSS／Sass をサポートするために必要です
✅ YAML 設定を使用する（--format yaml）- TOML より CMS との互換性が高くなります
✅ テーマを Git サブモジュールとして追加する - 更新とバージョン管理が簡単になります
✅ 正しい baseURL を設定する - デプロイ時にアセットのリンクが壊れるのを防ぎます
✅ CI/CD で Hugo のバージョンを固定する - ローカルとデプロイ環境のバージョン不一致によるエラーを防ぎます
✅ .gitignore に public/ を追加する - ビルド出力をコミットしないようにします
✅ draft: false を使用する - ドラフトは本番ビルドに表示されません
✅ --recursive フラグを付けてクローンする - テーマのサブモジュールを確実に取得できます
✅ 画像には相対パスを使用する - ../images/photo.jpg ではなく /images/photo.jpg を使用します
✅ デプロイ前にビルドをテストする - hugo --minify でローカルのエラーを見つけます

絶対に行わないこと

❌ Hugo Standard をインストールしない - ほとんどのテーマで Extended エディションが必要です
❌ Sveltia CMS で TOML 設定を使用しない - 既知のバグがあるため、代わりに YAML を使用してください
❌ public/ ディレクトリをコミットしない - 生成された出力であり、ソースコードではありません
❌ 異なる Hugo バージョンを使用しない - ローカルと CI/CD のバージョン不一致によりエラーが発生します
❌ submodules: recursive を忘れない - CI/CD でテーマが読み込まれなくなります
❌ 本番環境の URL をハードコードしない - -b $CF_PAGES_URL または環境設定を使用してください
❌ resources/_gen/ をプッシュしない - 生成されたアセットなので、.gitignore に含めてください
❌ 未来の日付を安易に使用しない - 日付が過ぎるまで投稿は公開されません
❌ .hugo_build.lock を除外し忘れない - .gitignore に追加してください
❌ YAML と TOML を混在させない - プロジェクト全体で形式を統一してください

---

よくあるエラーを防ぐためのトップ 5

このスキルでは、記録されている 15 件のエラーを防ぎます。特に多い 5 件を以下に示します。

エラー #1: バージョンの不一致（Hugo と Hugo Extended）

エラー: Error: SCSS support not enabled
予防策: 必ず Hugo Extended エディションをインストールしてください。hugo version | grep extended で確認します
参照: エラー一覧は references/error-catalog.md を参照してください

エラー #2: baseURL の設定エラー

エラー: CSS／JS／画像のリンクが壊れる、すべてのアセットで 404 が発生する
予防策: 環境別の設定、またはビルドフラグ hugo -b $CF_PAGES_URL を使用してください
参照: references/error-catalog.md #2

エラー #3: テーマが見つからないエラー

エラー: Error: module "PaperMod" not found、サイトが空白になる
予防策: hugo.yaml に theme: "PaperMod" を設定し、git submodule update --init --recursive を実行してください
参照: references/error-catalog.md #6

エラー #4: Hugo バージョンの不一致（ローカルとデプロイ環境）

エラー: ローカルでは動作する機能が CI/CD では失敗する、またはその逆
予防策: あらゆる環境（CI/CD、ローカルのドキュメント、npm を使用する場合は package.json）で Hugo のバージョンを固定してください
参照: references/error-catalog.md #4

エラー #5：CI/CD で Git サブモジュールが見つからない

エラー：ローカルではテーマが機能するが、CI/CD では機能せず、デプロイ時にサイトが空白になる 予防策：GitHub Actions のチェックアウトアクションに submodules: recursive を追加します 参照：references/error-catalog.md #11

エラーカタログ全体（全15件）：references/error-catalog.md を参照してください

---

同梱リソースの使用

参照資料（references/）：

• setup-guide.md - Hugo のセットアップ手順の完全ガイド（インストール、テーマ、デプロイ）
• error-catalog.md - よくある Hugo のエラー15件と、その解決策および予防策
• common-patterns.md - ベストプラクティスとパターン（分類体系、コンテンツの整理、多言語対応）
• cms-integration.md - Sveltia CMS の設定を含む統合ガイド
• tailwind-integration.md - Hugo Pipes を使った Tailwind CSS の統合
• advanced-topics.md - Hugo の高度な機能（モジュール、データファイル、国際化）

テンプレート（templates/）

コピーしてすぐに使える、本番環境対応の完全な Hugo プロジェクトです。

• templates/hugo-blog/ - PaperMod テーマを使ったブログ

  • ダーク／ライトモード、検索、タグ、アーカイブ
  • Sveltia CMS の設定済み
  • Workers へのデプロイ用 wrangler.jsonc
  • GitHub Actions のワークフローを同梱
  • 使用する場面：個人ブログ、企業ブログ、ニュースサイトの構築

• templates/hugo-docs/ - Hugo Book テーマを使ったドキュメントサイト

  • 階層型ナビゲーション、検索、パンくずリスト
  • ドキュメント編集用の Sveltia CMS
  • 使用する場面：技術ドキュメント、ナレッジベース、API ドキュメントの作成

• templates/hugo-landing/ - カスタムレイアウトを使ったランディングページ

  • ヒーロー、機能紹介、お客様の声、CTA セクション
  • テーマへの依存なし（カスタムレイアウト）
  • コンバージョン向けに最適化
  • 使用する場面：マーケティングサイト、製品ページ、ポートフォリオの構築

• templates/minimal-starter/ - 最小限のスターター

  • テーマなし、自由に構築可能
  • テーマの追加方法を説明するセットアップガイド
  • 最小限の設定
  • 使用する場面：完全な制御を保ちながら、ゼロから始める場合

テンプレートを使ったクイックスタート：

cp -r templates/hugo-blog/ my-new-blog/
cd my-new-blog
git submodule update --init --recursive
hugo server

参照資料（references/）

必要に応じて読み込める詳細ガイドです。

• references/setup-guide.md - 7ステップの完全なセットアップ手順

  • インストールと確認
  • プロジェクトのひな形作成
  • テーマのインストール
  • 設定オプション
  • コンテンツの作成
  • ビルドと開発
  • Cloudflare Workers へのデプロイ
  • 読み込む場面：Hugo プロジェクトをゼロから新規セットアップするとき

• references/cms-integration.md - ヘッドレス CMS の統合

  • Sveltia CMS のセットアップ（推奨）- 5分
  • 本番環境用の OAuth 設定
  • TinaCMS のセットアップ（非推奨）
  • 比較とトラブルシューティング
  • 読み込む場面：Hugo サイトにコンテンツ管理機能を追加するとき

• references/tailwind-integration.md - Tailwind CSS v4 の統合

  • Hugo Pipes と PostCSS のセットアップ
  • ダークモードの実装（CSS のみ、および Alpine.js）
  • Typography プラグインと Forms プラグイン
  • 本番環境向けの最適化
  • よくある問題と解決策
  • 読み込む場面：Tailwind CSS を Hugo に統合するとき

• references/common-patterns.md - よく使われる7つのプロジェクトパターン

  • PaperMod を使ったブログ
  • Hugo Book を使ったドキュメント
  • ランディングページ
  • 多言語サイト
  • ポートフォリオサイト
  • Eコマース（静的）
  • ニュースレター／ブログ
  • 読み込む場面：特定の用途に適したアーキテクチャを選ぶとき

• references/advanced-topics.md - Hugo の高度な機能

  • カスタムショートコード
  • 画像処理
  • カスタム分類体系
  • データファイル（JSON/YAML/CSV）
  • ページバンドル
  • テンプレートのオーバーライド
  • Hugo Modules
  • 読み込む場面：高度なカスタマイズが必要なとき

• references/error-catalog.md - ドキュメント化されたエラー全15件

  • 完全なエラーメッセージと解決策
  • 予防策
  • 公式情報源の引用
  • トラブルシューティングガイド
  • 読み込む場面：問題のデバッグや既知のエラーの予防を行うとき

---

よくあるユースケース

ユースケース 1：個人ブログ

テンプレート：templates/hugo-blog/ テーマ：PaperMod デプロイ時間：10 分 機能：検索、タグ、ダークモード、RSS、Sveltia CMS

cp -r templates/hugo-blog/ my-blog/
cd my-blog
git submodule update --init --recursive
hugo new content posts/first-post.md
hugo server

references/common-patterns.md → パターン 1 を参照してください。

ユースケース 2：技術ドキュメント

テンプレート：templates/hugo-docs/ テーマ：Hugo Book デプロイ時間：10 分 機能：階層型ナビゲーション、検索、パンくずリスト、多言語対応

cp -r templates/hugo-docs/ docs-site/
cd docs-site
git submodule update --init --recursive
hugo new content docs/getting-started/installation.md
hugo server

references/common-patterns.md → パターン 2 を参照してください。

ユースケース 3：ランディングページ

テンプレート：templates/hugo-landing/ テーマ：なし（カスタムレイアウト） デプロイ時間：15 分 機能：ヒーロー、機能紹介、お客様の声、CTA、お問い合わせフォーム

cp -r templates/hugo-landing/ landing/
cd landing
hugo server

references/common-patterns.md → パターン 3 を参照してください。

ユースケース 4：Tailwind CSS v4 を使用したブログ

テンプレート：templates/minimal-starter/ から開始 統合方法：references/tailwind-integration.md に従ってください セットアップ時間：30 分 機能：カスタムデザイン、ユーティリティファースト CSS、ダークモード

cp -r templates/minimal-starter/ tailwind-blog/
cd tailwind-blog
# Follow references/tailwind-integration.md for setup

references/tailwind-integration.md → クイックスタートを参照してください。

ユースケース 5：多言語ドキュメント

テンプレート：templates/hugo-docs/ パターン：多言語 セットアップ時間：20 分 機能：言語切り替え、翻訳済みコンテンツ、言語ごとのメニュー

references/common-patterns.md → パターン 4 を参照してください。

---

Cloudflare Workers へのデプロイ

クイックデプロイ

1. wrangler.jsonc を作成：

{
  "name": "my-hugo-site",
  "compatibility_date": "2025-01-29",
  "assets": {
    "directory": "./public",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page"
  }
}

2. デプロイ：

hugo --minify
bunx wrangler deploy

完全なデプロイガイド： references/setup-guide.md → ステップ 7 を参照してください。

---

詳細なリファレンスを読み込むタイミング

references/setup-guide.md を読み込む場合：

• ユーザーが 7 ステップのセットアップ手順全体を必要としている
• ユーザーが設定オプションについて質問している
• ユーザーが詳細なインストール手順を必要としている
• ユーザーがディレクトリ構成について質問している
• ユーザーが GitHub Actions のワークフローを必要としている

references/cms-integration.md を読み込む場合：

• ユーザーが Hugo サイトに CMS を追加したい
• ユーザーが Sveltia CMS のセットアップについて質問している
• ユーザーが TinaCMS について質問している（推奨されないことを伝えてください）
• ユーザーが OAuth の設定を必要としている
• ユーザーがコンテンツ管理について質問している

references/tailwind-integration.md を読み込む場合：

• ユーザーが Tailwind CSS v4 を統合したい
• ユーザーが PostCSS のセットアップについて質問している
• ユーザーがダークモードの実装を必要としている
• ユーザーが Tailwind プラグインについて質問している
• ユーザーに CSS 処理エラーが発生している

references/common-patterns.md を読み込む場合：

• ユーザーが「[ブログ／ドキュメント／ランディングページ] はどう作ればよいですか？」と質問している
• ユーザーがアーキテクチャの指針を必要としている
• ユーザーが多言語サイトについて質問している
• ユーザーがポートフォリオサイトについて質問している
• ユーザーがプロジェクト構成の例を必要としている

references/advanced-topics.md を読み込む場合：

• ユーザーがショートコードについて質問している
• ユーザーが画像処理を必要としている
• ユーザーがカスタムタクソノミーを使いたい
• ユーザーがデータファイルについて質問している
• ユーザーがテンプレートのカスタマイズを必要としている

references/error-catalog.md を読み込む場合：

• ユーザーにエラーが発生している
• ユーザーがトラブルシューティングについて質問している
• ユーザーが既知の問題を防ぎたい
• ユーザーが「どのようなエラーに注意すべきですか？」と質問している
• ユーザーにデプロイの問題が発生している

---

依存関係

必須：

• Hugo v0.159.2+（Extended エディション） - 静的サイトジェネレーター（セキュリティの最低要件：CVE-2026-35166 の XSS は 0.159.2 で修正済み。最新の安定版は 0.164.0）

任意（デプロイ用）：

• wrangler v4.0.0+ - Cloudflare Workers へのデプロイ
• Git v2.0+ - バージョン管理とテーマのサブモジュール

任意（CMS 用）：

• Sveltia CMS（最新） - コンテンツ管理（CDN ベース、インストール不要）

---

公式ドキュメント

• Hugo：https://gohugo.io/documentation/
• PaperMod Theme：https://github.com/adityatelange/hugo-PaperMod/wiki
• Hugo Book Theme：https://github.com/alex-shpak/hugo-book
• Sveltia CMS：https://github.com/sveltia/sveltia-cms
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hugo Themes：https://themes.gohugo.io/

---

パッケージのバージョン（2026-08-03 に確認済み）

Hugo：v0.164.0+extended（2026 年 7 月 6 日） PaperMod：最新（Git サブモジュール経由） Sveltia CMS：最新（CDN 経由） Wrangler：v4.37.1+（v4.45.3 が利用可能）

---

本番環境での実例

このスキルは、実環境でのテストに基づいています。

• テストサイト: https://hugo-blog-test.webfonts.workers.dev
• ビルド時間: 24ms（20 ページ）
• デプロイ時間: 約21秒
• エラー: 0件（既知の問題15件をすべて防止）
• 検証: ✅ Hugo + PaperMod + Sveltia + Workers のデプロイに成功しました

---

セットアップの完全チェックリスト

このチェックリストを使って、セットアップを確認してください。

• Hugo Extended v0.159.2+ がインストールされている（hugo version に「+extended」と表示される）
• --format yaml を指定してプロジェクトを作成している（hugo.yaml が存在する）
• テーマをインストールして設定している（Git サブモジュールまたは Hugo Module を使用）
• hugo.yaml で baseURL を正しく設定している
• .gitignore に public/ と resources/_gen/ が含まれている
• サンプルコンテンツを作成し、正しくレンダリングされる
• 開発サーバーがエラーなく起動する（hugo server）
• 本番ビルドが成功する（hugo --minify）
• Workers にデプロイする場合、wrangler.jsonc を設定している
• CMS を使用する場合、Sveltia CMS を設定している
• CI/CD を使用する場合、GitHub Actions ワークフローを設定している
• Workers にデプロイする場合、デプロイが成功している

---

ご質問や問題がありますか？

1. references/error-catalog.md で、文書化されているエラー15件とその解決策を確認してください
2. セットアップ手順のすべてのステップを確認してください
3. templates/ ディレクトリから適切なテンプレートを使用してください
4. 詳細については、関連するリファレンスガイドを読み込んでください
5. 公式ドキュメントを確認してください: https://gohugo.io/documentation/

---

このスキルは、エラーのない本番環境対応の Hugo セットアップを提供します。よくある問題15件をすべて文書化し、発生を防止しています。