hugo

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

ステータス：本番環境で使用可能 最終更新日：2025-11-04 依存関係：なし（Hugo はスタンドアロンバイナリです） 最新バージョン：[email protected]+extended、PaperMod@latest、Sveltia CMS@latest

---

クイックスタート（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.152.2/hugo_extended_0.152.2_linux-amd64.deb
sudo dpkg -i hugo_extended_0.152.2_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

重要：

• --format yaml を使用して hugo.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

---

7 ステップのセットアップ手順

ステップ 1：インストールと確認

以下のいずれかの方法で Hugo Extended をインストールします。

方法 1：Homebrew（macOS/Linux） ✅ 推奨

brew install hugo

方法 2：バイナリのダウンロード（Linux）

# Check latest version: https://github.com/gohugoio/hugo/releases
VERSION="0.152.2"
wget https://github.com/gohugoio/hugo/releases/download/v${VERSION}/hugo_extended_${VERSION}_linux-amd64.deb
sudo dpkg -i hugo_extended_${VERSION}_linux-amd64.deb

方法 3：Docker

docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-alpine

方法 4：NPM ラッパー（非推奨。最新のリリースより遅れている可能性があります）

npm install -g hugo-bin

確認：

hugo version
# Should output: hugo v0.152.2+extended
#                                ^^^^^^^^ Must show "+extended"

要点：

• SCSS/Sass には Extended エディションが必要です
• 互換性を高めるには、バージョン v0.149.0 以上を使用してください
• NPM ラッパーは公式リリースより遅れている場合があります
• CI/CD ではバージョンを固定してください（ステップ 7 を参照）

ステップ 2：プロジェクトのひな型作成

YAML 設定で新しいサイトを作成します。

hugo new site my-site --format yaml
cd my-site

作成されるディレクトリ構成：

my-site/
├── hugo.yaml          # Configuration (YAML format)
├── archetypes/        # Content templates
│   └── default.md
├── content/           # All your content goes here
├── data/              # Data files (JSON/YAML/TOML)
├── layouts/           # Template overrides
├── static/            # Static assets (images, CSS, JS)
├── themes/            # Themes directory
└── public/            # Build output (generated, git ignore)

重要：

• CMS との互換性のため、--format yaml を使用してください
• public/ ディレクトリを Git にコミットしないでください
• すぐに .gitignore を作成してください（ステップ 3 を参照）

ステップ 3：テーマのインストール

推奨方法：Git サブモジュール ✅

# Popular themes:
# - PaperMod (blogs): https://github.com/adityatelange/hugo-PaperMod
# - Book (docs): https://github.com/alex-shpak/hugo-book
# - Academic (research): https://github.com/HugoBlox/theme-academic-cv
# - Ananke (general): https://github.com/theNewDynamic/gohugo-theme-ananke

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

別の方法：Hugo Modules（上級者向け）

hugo mod init github.com/username/my-site

# In hugo.yaml:
# module:
#   imports:
#     - path: github.com/adityatelange/hugo-PaperMod

hugo.yaml にテーマを追加します。

theme: "PaperMod"

サブモジュールを含むプロジェクトをクローンする場合：

git clone --recursive https://github.com/username/my-site.git
# Or if already cloned:
git submodule update --init --recursive

要点：

• 手動ダウンロードよりも Git サブモジュールを推奨します
• --depth=1 を指定するとテーマの履歴を取得せずに済み、容量を節約できます
• クローン後は必ず git submodule update --init --recursive を実行してください
• Hugo Modules はより高度ですが、Git サブモジュールは不要です

ステップ 4：設定

hugo.yaml - 完全な例（PaperMod ブログ）：

baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
defaultContentLanguage: "en"
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  author: "Your Name"
  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  defaultTheme: auto  # dark, light, auto

  socialIcons:
    - name: twitter
      url: "https://twitter.com/username"
    - name: github
      url: "https://github.com/username"

menu:
  main:
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 10
    - identifier: about
      name: About
      url: /about/
      weight: 20

outputs:
  home:
    - HTML
    - RSS
    - JSON  # Required for search

設定形式：

• YAML（推奨）：hugo.yaml - CMS との互換性が高くなります
• TOML（レガシー）：hugo.toml - デフォルトですが、Sveltia CMS との相性に問題があります
• JSON：hugo.json - あまり使用されません

環境ごとの設定：

config/
├── _default/
│   └── hugo.yaml
├── production/
│   └── hugo.yaml  # Overrides for production
└── development/
    └── hugo.yaml  # Overrides for local dev

ステップ 5：コンテンツの作成

Hugo CLI でコンテンツを作成します。

# Blog post
hugo new content posts/my-first-post.md

# Page
hugo new content about.md

# Nested documentation
hugo new content docs/getting-started/installation.md

フロントマター形式（YAML を推奨）：

---
title: "My First Post"
date: 2025-11-04T10:00:00+11:00
draft: false
tags: ["hugo", "blog"]
categories: ["General"]
description: "A brief description for SEO"
cover:
  image: "/images/cover.jpg"
  alt: "Cover image"
---

# Post content starts here

This is my first Hugo blog post!

TOML フロントマター（参考のみ）：

+++
title = "My First Post"
date = 2025-11-04T10:00:00+11:00
draft = false
tags = ["hugo", "blog"]
+++

要点：

• YAML フロントマターには --- 区切りを使用してください
• TOML フロントマターには +++ 区切りを使用してください
• 本番環境で投稿を表示するには draft: false が必要です
• date が未来の日付の場合、投稿は公開されません（--buildFuture フラグを使用した場合を除く）
• コンテンツはフロントマターの閉じ区切りの後に記述します

ステップ 6：ビルドと開発

ライブリロード付きの開発サーバー：

# Start server
hugo server

# With drafts visible
hugo server --buildDrafts

# With future-dated posts
hugo server --buildFuture

# Bind to specific port
hugo server --port 1314

# Access at: http://localhost:1313

本番ビルド：

# Basic build
hugo

# With minification (recommended)
hugo --minify

# With specific baseURL (for deployment)
hugo --minify --baseURL https://example.com

# Or use environment variable
hugo --minify -b $CF_PAGES_URL

ビルド出力：

• 生成されたファイルはすべて public/ ディレクトリに出力されます
• 標準的なビルド時間：小規模サイトでは 100ms 未満、1000 ページ以上では 5 秒未満です
• Hugo は静的サイトジェネレーターの中で最速です

要点：

• 開発サーバーではライブリロード（HMR）が有効です
• 本番ビルドでは --minify を使用してください
• public/ ディレクトリをコミットしないでください
• Hugo は Go で書かれているため、ビルド時間は非常に短くなります

ステップ 7：Cloudflare Workers へのデプロイ

wrangler.jsonc を作成します：

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

手動でデプロイする場合：

# Build site
hugo --minify

# Deploy to Workers
npx wrangler deploy

GitHub Actions（自動）：

.github/workflows/deploy.yml を作成します：

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Important for theme submodules!

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.152.2'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

重要なポイント：

• assets.directory は "./public"（Hugo の出力先）にする必要があります
• html_handling: "auto-trailing-slash" は Hugo の URL 構造に対応します
• not_found_handling: "404-page" は Hugo の 404.html を配信します
• CI/CD では常に Hugo のバージョンを固定してください（バージョン不一致エラーを防止します）
• テーマのサブモジュールには submodules: recursive を使用してください

---

重要なルール

必ず行うこと

✅ Hugo Extended をインストールする（Standard ではありません）— テーマで SCSS/Sass をサポートするために必要です ✅ YAML 設定を使用する（--format yaml）— TOML よりも CMS との互換性に優れています ✅ テーマを Git サブモジュールとして追加する— 更新とバージョン管理が容易になります ✅ 正しい baseURL を設定する— デプロイ時のアセットリンク切れを防ぎます ✅ CI/CD で Hugo のバージョンを固定する— ローカルとデプロイ環境のバージョン不一致によるエラーを防ぎます ✅ public/ を .gitignore に追加する— ビルド出力をコミットしないようにします ✅ 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 を混在させない— プロジェクト全体でどちらか一方の形式に統一してください

---

既知の問題を防ぐ

このスキルは、記録されている 9 件の問題を防ぎます：

問題 #1：バージョン不一致（Hugo と Hugo Extended）

エラー：Error: SCSS support not enabled 出典：https://gohugo.io/troubleshooting/faq/#i-get-this-feature-is-not-available-in-your-current-hugo-version 発生する理由：テーマで SCSS/Sass の処理が必要ですが、Hugo Standard には含まれていません 防止策：必ず Hugo Extended エディションをインストールしてください。hugo version | grep extended で確認してください

問題 #2：baseURL の設定エラー

エラー：CSS/JS/画像のリンク切れ、すべてのアセットで 404 が発生 出典：Hugo のドキュメント、Cloudflare Pages のガイド 発生する理由：設定ファイルの baseURL がデプロイ URL と一致していません 防止策：

• 環境ごとの設定を使用します（config/production/hugo.yaml）
• またはビルドフラグを使用します：hugo -b $CF_PAGES_URL
• またはビルド前に hugo.yaml で正しい baseURL を設定します

問題 #3：TOML と YAML の設定に関する混乱

エラー：Sveltia CMS がフロントマターを解析できない、設定が読み込まれない 出典：Sveltia CMS のドキュメント、コミュニティからの報告 発生する理由：TOML と YAML を混在させる、または（バグのある）Sveltia CMS で TOML を使用する 防止策：YAML 形式に統一します。--format yaml フラグを使ってサイトを作成してください

問題 #4：Hugo のバージョン不一致（ローカルとデプロイ環境）

エラー：ローカルでは機能する機能が CI/CD では失敗する、またはその逆 出典：GitHub Actions の hugo-setup、Cloudflare Pages のドキュメント 発生する理由：Hugo のバージョンが異なると、利用可能な機能やバグも異なります 防止策：

• hugo.yaml のメタデータまたは README で Hugo のバージョンを固定します
• Cloudflare Pages で HUGO_VERSION を設定します
• GitHub Actions で hugo-version: '0.152.2' を使用します

Issue #5: コンテンツのフロントマター形式エラー

エラー：コンテンツファイルがレンダリングされず、解析エラーでビルドに失敗します 出典：Hugo のコンテンツ管理ドキュメント 原因：区切り文字が誤っている（--- と +++ の取り違え）、または YAML／TOML の構文が無効です 予防策：

• YAML：--- 区切り文字を使用します
• TOML：+++ 区切り文字を使用します
• Sveltia CMS または YAML リンターでフロントマターを検証します

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

エラー：Error: module "PaperMod" not found、サイトが空白になります 出典：Hugo のテーマに関するドキュメント 原因：テーマがインストールされていない、設定で theme が指定されていない、または Git サブモジュールが初期化されていません 予防策：

• hugo.yaml に theme: "PaperMod" を設定します
• git submodule add を使用してテーマをインストールします
• クローン後は必ず git submodule update --init --recursive を実行します

Issue #7: 日付のタイムワープ問題

エラー：デプロイしたサイトではコンテンツが表示されないのに、ローカルでは表示されます 出典：Hugo の日付処理に関するドキュメント 原因：未来の日付が設定された投稿がローカルでは公開されている（--buildFuture を使用）が、本番環境では公開されていません 予防策：

• フロントマターでは現在または過去の日付を使用します
• または、本番ビルドに --buildFuture フラグを追加します
• フロントマターの date フィールドを確認します

Issue #8: public フォルダーの競合

エラー：サイトに古いコンテンツが表示される、public/ で Git の競合が発生する 出典：Hugo のプロジェクト構造に関するベストプラクティス 原因：ビルド出力専用にすべき public/ ディレクトリをコミットしています 予防策：

• .gitignore に public/ を追加します
• デプロイのたびに再ビルドします
• 生成されたファイルは決してコミットしません

Issue #9: モジュールキャッシュの問題

エラー：failed to extract shortcode、モジュールキャッシュが破損しています 出典：Hugo Modules のドキュメント、GitHub のイシュー 原因：Hugo Modules のキャッシュが破損しています（サブモジュールではなくモジュールを使用している場合） 予防策：

• hugo mod clean を実行してキャッシュをクリアします
• 定期的に hugo mod tidy を実行します
• または、モジュールの代わりに Git サブモジュールを使用します（より信頼性があります）

---

設定ファイルのリファレンス

hugo.yaml（本番環境向けの完全な例）

baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
defaultContentLanguage: "en"
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true
pygmentsUseClasses: true
summaryLength: 30

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  keywords: [Blog, Hugo, Tech]
  author: "Your Name"
  images: ["/images/og-image.jpg"]
  DateFormat: "January 2, 2006"
  defaultTheme: auto  # dark, light, auto
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: true
  tocopen: false

  assets:
    disableHLJS: true
    disableFingerprinting: false

  label:
    text: "My Hugo Blog"
    icon: /favicon.ico
    iconHeight: 35

  homeInfoParams:
    Title: "Hi there 👋"
    Content: Welcome to my blog.

  socialIcons:
    - name: twitter
      url: "https://twitter.com/"
    - name: github
      url: "https://github.com/"
    - name: linkedin
      url: "https://linkedin.com/"
    - name: rss
      url: "/index.xml"

  cover:
    hidden: false
    hiddenInList: false
    hiddenInSingle: false

  editPost:
    URL: "https://github.com/username/repo/tree/main/content"
    Text: "Suggest Changes"
    appendFilePath: true

  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    keys: ["title", "permalink", "summary", "content"]

menu:
  main:
    - identifier: search
      name: Search
      url: /search/
      weight: 10
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 20
    - identifier: archives
      name: Archives
      url: /archives/
      weight: 30
    - identifier: tags
      name: Tags
      url: /tags/
      weight: 40
    - identifier: about
      name: About
      url: /about/
      weight: 50

outputs:
  home:
    - HTML
    - RSS
    - JSON  # Required for search functionality

これらの設定の理由：

• buildDrafts: false - 本番環境で下書きが含まれないようにします
• enableRobotsTXT: true - SEO のベストプラクティスです
• minifyOutput: true - ファイルサイズを小さくします
• defaultTheme: auto - ユーザーのシステム設定を反映します
• JSON 出力 - クライアント側検索を有効にします
• ソーシャルアイコン - 見つけやすさを向上させます

wrangler.jsonc（Cloudflare Workers）

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

これらの設定の理由：

• directory: "./public" - Hugo のビルド出力です
• html_handling: "auto-trailing-slash" - Hugo の URL 構造に合わせます
• not_found_handling: "404-page" - Hugo のカスタム 404.html を配信します

.gitignore（必須）

# Hugo
/public/
/resources/_gen/
.hugo_build.lock

# OS
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/
*.swp
*.swo

# Dependencies (if using npm for tools)
node_modules/
package-lock.json

# Logs
*.log

---

Sveltia CMS との統合（推奨）

Hugo に Sveltia CMS を使用する理由

✅ Hugo は Sveltia の主な用途です - Hugo 専用に設計されています ✅ 簡単なセットアップ - 静的ファイル 2 つだけで、ビルド手順は不要です ✅ npm 依存関係なし - CDN スクリプト 1 つだけです ✅ ローカルバックエンド - Git なしで CMS をローカルでテストできます ✅ YAML フロントマター - 完全に互換性があります ✅ セキュリティ上の脆弱性なし - 軽量で、メンテナンスされています ✅ 活発な開発 - 静的サイトジェネレーターに注力しています

セットアップ（5 分）

1. 管理画面を作成 - static/admin/index.html：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Content Manager</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
  </body>
</html>

2. CMS 設定を作成 - static/admin/config.yml：

backend:
  name: git-gateway
  branch: main

local_backend: true  # Enable local testing

media_folder: "static/images/uploads"
public_folder: "/images/uploads"

collections:
  - name: "blog"
    label: "Blog Posts"
    folder: "content/posts"
    create: true
    slug: "{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Description", name: "description", widget: "string", required: false}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Tags", name: "tags", widget: "list", required: false}
      - {label: "Categories", name: "categories", widget: "list", required: false}
      - {label: "Cover Image", name: "cover", widget: "object", required: false, fields: [
          {label: "Image", name: "image", widget: "image", required: false},
          {label: "Alt Text", name: "alt", widget: "string", required: false}
        ]}
      - {label: "Body", name: "body", widget: "markdown"}

  - name: "pages"
    label: "Pages"
    folder: "content"
    create: true
    slug: "{{slug}}"
    filter: {field: "type", value: "page"}
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Type", name: "type", widget: "hidden", default: "page"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Body", name: "body", widget: "markdown"}

3. サイトを再ビルド：

hugo
# Admin interface now at: http://localhost:1313/admin

4. 本番環境の OAuth（Git バックエンドの場合）：

Sveltia CMS で本番環境の GitHub／GitLab 認証を使用するには、OAuth が必要です。OAuth プロキシには Cloudflare Workers を使用します。

同梱のリファレンスを参照してください：references/sveltia-integration-guide.md

主なポイント：

• ビルド後、/admin から管理画面にアクセスできます
• local_backend: true を指定すると、Git なしでローカルテストができます
• YAML フロントマター形式が必要です
• コレクションは Hugo のコンテンツディレクトリに対応します
• メディアファイルは static/images/uploads に保存されます

---

TinaCMS との統合（非推奨）

⚠️ 代わりに Sveltia CMS を使用してください。TinaCMS には Hugo で使用する際に大きな制約があります：

TinaCMS を選ばない理由

❌ React 専用のビジュアル編集 - Hugo は Go のテンプレートを使用するため、ビジュアル編集は機能しません ❌ 複雑なセットアップ - Node.js サーバーまたは Tina Cloud が必要です ❌ 692 個の npm パッケージ - Sveltia は CDN スクリプトが 1 つです ❌ 7 件のセキュリティ脆弱性 - （2025-11-04 時点で高 4 件、重大 3 件） ❌ React/Next.js に特化 - Hugo は主な用途ではありません ❌ YAML のみ - Sveltia と同じ制限があり、利点はありません

TinaCMS を使わざるを得ない場合

次の場合に限り、TinaCMS の使用を検討してください：

• すでに Tina Cloud を使用している
• React の専門知識を持つ人材を確保できる
• Tina 固有の機能が必要

同梱のリファレンスをご覧ください：references/tinacms-integration-guide.md（警告：推奨されません）

---

Tailwind CSS v4 の統合

Hugo は Hugo Pipes と Tailwind CLI を通じて Tailwind CSS v4 をサポートしています。この方法は、Vite ベースの React プロジェクトとは根本的に異なります。

Tailwind とテーマの使い分け

次の場合は Hugo で Tailwind を使用します：

• テーマに依存せず、カスタムデザインを構築する
• ユーティリティファーストの CSS ワークフローが必要
• スタイルを完全に制御したい
• SCSS/Sass より Tailwind を使いたい

次の場合はテーマ（PaperMod、Book など）を使用します：

• 実績のある、本番環境ですぐに使えるデザインを求める
• カスタム CSS を使わずにすばやくセットアップしたい
• テーマのカスタマイズオプションで十分である
• ピクセル単位のカスタムデザインが不要

Vite + React との主な違い

重要： Hugo で tailwind-v4-shadcn スキルのパターンを使用しないでください。このスキルは Vite + React プロジェクト向けであり、Hugo のアセットパイプラインとは互換性がありません。

項目	Vite + React	Hugo
ビルドシステム	JavaScript（Node.js）	Go（Hugo バイナリ）
Tailwind の統合	@tailwindcss/vite プラグイン	Tailwind CLI + PostCSS
設定ファイル	vite.config.ts	hugo.yaml
コンテンツのスキャン	content: [] グロブ	hugo_stats.json
開発サーバー	Vite（ポート 5173）	Hugo（ポート 1313）
ダークモード	React ThemeProvider	CSS クラスまたは Alpine.js

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

1. 依存関係をインストール

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

2. Hugo を設定（hugo.yaml）

build:
  writeStats: true  # Generates hugo_stats.json for Tailwind

module:
  mounts:
    - source: assets
      target: assets
    - source: hugo_stats.json
      target: assets/watching/hugo_stats.json

3. Tailwind を設定（tailwind.config.js）

module.exports = {
  content: [
    './hugo_stats.json',
    './layouts/**/*.html',
    './content/**/*.{html,md}',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: '#0066cc',
      },
    },
  },
  plugins: [],
}

4. PostCSS を設定（postcss.config.js）

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

5. CSS エントリーファイルを作成（assets/css/main.css）

@import "tailwindcss";

@layer base {
  body {
    @apply bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100;
  }
}

6. テンプレートで CSS を処理（layouts/_default/baseof.html）

<head>
  {{ $style := resources.Get "css/main.css" | resources.PostCSS }}
  {{ if hugo.IsProduction }}
    {{ $style = $style | minify | fingerprint }}
  {{ end }}
  <link rel="stylesheet" href="{{ $style.RelPermalink }}">
</head>

7. 開発を開始

hugo server

統合ガイド全文

以下を含む Tailwind v4 + Hugo の完全なセットアップについて：

• ダークモードの実装（CSS のみ、および Alpine.js）
• Typography プラグインのセットアップ
• Forms プラグインのセットアップ
• テンプレート統合のパターン
• よくある問題と解決策
• 本番ビルドの最適化

同梱リソースをご覧ください：

• リファレンスガイド：references/tailwind-v4-integration.md（包括的なドキュメント）
• 最小限のテンプレート：templates/hugo-tailwind-minimal/（出発点）
• ブログテンプレート：templates/hugo-tailwind-blog/（Tailwind を使った完全なブログ）

Tailwind 固有の問題

Hugo で Tailwind を使う際によくある問題（すべてリファレンスガイドに解決策とともに記載）：

問題	原因	解決策
CSS が処理されない	PostCSS が設定されていない	テンプレート内の resources.PostCSS を確認
クラスがパージされない	hugo_stats.json が生成されない	hugo.yaml で writeStats: true を有効にする
ダークモードが機能しない	設定が間違っている	tailwind.config.js で darkMode: 'class' を使用
アセットのフィンガープリント処理に失敗する	Hugo Pipes の使い方が正しくない	Permalink ではなく RelPermalink を使用
CSS 内の Hugo テンプレート構文	CSS 内では {{ }} を使用できない	CSS ではなくテンプレートにクラスを適用
バージョンの不一致	CLI と PostCSS プラグインのバージョンが異なる	すべてを同じバージョンに更新

---

よくあるパターン

パターン 1：PaperMod テーマを使ったブログ

# Scaffold
hugo new site my-blog --format yaml
cd my-blog
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# Configure (see hugo.yaml example above)

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

# Develop
hugo server

# Build
hugo --minify

使用場面：個人ブログ、企業ブログ、ニュースサイト

パターン 2：Hugo Book を使ったドキュメントサイト

# Scaffold
hugo new site docs --format yaml
cd docs
git init
git submodule add https://github.com/alex-shpak/hugo-book.git themes/hugo-book

# Configure for docs (nested navigation, search)
# See: bundled template `templates/hugo-docs/`

# Create docs
hugo new content docs/getting-started/installation.md

# Build
hugo --minify

使用場面：技術ドキュメント、ナレッジベース、API ドキュメント

パターン 3：ランディングページ

# Scaffold
hugo new site landing --format yaml

# Use custom layouts (no theme)
# See: bundled template `templates/hugo-landing/`

# Single-page structure
hugo new content _index.md

# Build
hugo --minify

使用する場面：マーケティングサイト、製品ページ、ポートフォリオ

パターン 4：多言語サイト

# hugo.yaml
defaultContentLanguage: "en"
languages:
  en:
    languageName: "English"
    weight: 1
  es:
    languageName: "Español"
    weight: 2

# Content structure:
# content/
# ├── posts/
# │   └── post-1.en.md
# │   └── post-1.es.md

使用する場面：国際的なサイト、ローカライズされたコンテンツ

---

バンドルされたリソースの使用

スクリプト（scripts/）

init-hugo.sh — Hugo プロジェクトのセットアップを自動化します

./scripts/init-hugo.sh blog my-blog
# Creates Hugo site with specified template (blog/docs/landing/minimal)
# Arguments: [template-type] [project-name]

deploy-workers.sh — Cloudflare Workers への手動デプロイ

./scripts/deploy-workers.sh
# Runs: hugo --minify && wrangler deploy

check-versions.sh — Hugo とツールのバージョンを確認します

./scripts/check-versions.sh
# Checks: Hugo version, Extended edition, wrangler, Node.js

テンプレート（templates/）

すぐにコピーして使える、完全に動作する Hugo プロジェクトです。

templates/hugo-blog/ — PaperMod テーマを使用したブログ

• ダーク／ライトモード、検索、タグ、アーカイブ
• Sveltia CMS の事前設定済み
• Workers 用の wrangler.jsonc
• GitHub Actions ワークフロー

templates/hugo-docs/ — ドキュメントサイト

• 階層型ナビゲーション、検索、パンくずリスト
• Hugo Book テーマ
• ドキュメント編集用の Sveltia CMS

templates/hugo-landing/ — ランディングページ

• ヒーロー、特徴、推薦コメント、CTA
• カスタムレイアウト（テーマなし）
• コンバージョン向けに最適化

templates/minimal-starter/ — 最小限のプロジェクト

• テーマなし、自由にカスタマイズ可能
• テーマ追加用のセットアップガイド
• 最小限の設定

テンプレートを使用する場面：新しいプロジェクトをすぐに始めるには、テンプレートディレクトリ全体をコピーします。

リファレンス（references/）

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

• references/sveltia-integration-guide.md — Sveltia CMS のセットアップ全般、OAuth の設定
• references/workers-deployment-guide.md — Cloudflare Workers へのデプロイ、CI/CD、カスタムドメイン
• references/common-errors.md — 9 件すべてのエラーと詳細な解決策
• references/theme-customization-guide.md — レイアウトの上書き、カスタム CSS、パーシャル
• references/hugo-vs-alternatives.md — Next.js、Astro、Jekyll との比較

Claude がこれらを読み込む場面：ユーザーが特定のトピック（CMS のセットアップ、デプロイ、エラー、テーマ設定、代替手段）について尋ねた場合

アセット（assets/）

• assets/screenshots/ — Hugo ブログ、Sveltia CMS、デプロイの視覚例
• assets/diagrams/ — Hugo のディレクトリ構成、デプロイのワークフロー図

---

高度なトピック

カスタムショートコード

再利用可能なコンテンツコンポーネントを作成します。

<div class="youtube-embed">
  <iframe
    src="https://www.youtube.com/embed/{{ .Get 0 }}"
    allowfullscreen>
  </iframe>
</div>

コンテンツ内での使用方法：

{{< youtube dQw4w9WgXcQ >}}

画像処理

Hugo には画像処理機能が組み込まれています。

{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x" }}
<img src="{{ $resized.RelPermalink }}" alt="Photo">

タクソノミーのカスタマイズ

タグやカテゴリー以外のカスタムタクソノミーを作成します。

# hugo.yaml
taxonomies:
  tag: tags
  category: categories
  series: series  # Custom taxonomy

データファイル

JSON／YAML／TOML のデータファイルを使用します。

# data/team.yaml
- name: Alice
  role: Developer
- name: Bob
  role: Designer

テンプレートでのアクセス方法：

{{ range .Site.Data.team }}
  <div>{{ .name }} - {{ .role }}</div>
{{ end }}

---

依存関係

必須：

• Hugo v0.149.0+（Extended 版）— 静的サイトジェネレーター

任意（デプロイ用）：

• 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
• Sveltia CMS：https://github.com/sveltia/sveltia-cms
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hugo Themes：https://themes.gohugo.io/

---

パッケージのバージョン（2025-11-04 に確認）

Hugo：v0.152.2+extended（2025 年 10 月 24 日） PaperMod：最新版（Git サブモジュール経由） Sveltia CMS：最新版（CDN 経由） Wrangler：v4.37.1+（v4.45.3 を利用可能）

---

本番環境での実例

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

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

---

トラブルシューティング

問題：「SCSS support not enabled」エラー

解決策：Standard ではなく Hugo Extended をインストールします。hugo version | grep extended で確認してください。

問題：デプロイ後にサイトが空白になる

解決策：

1. hugo.yaml で theme が設定されていることを確認します
2. themes/ ディレクトリにテーマが存在することを確認します
3. git submodule update --init --recursive を実行します

問題：アセット（CSS／JS／画像）が読み込まれない

解決方法：

1. hugo.yaml の baseURL がデプロイ先の URL と一致していることを確認します
2. または、hugo -b https://your-site.com を使用します
3. または、環境ごとの設定を使用します

問題：投稿がサイトに表示されない

解決方法：

1. フロントマターで draft: false になっていることを確認します
2. 日付が未来の日付ではないことを確認します
3. または、--buildDrafts と --buildFuture フラグを指定してビルドします

問題：CI/CD でテーマが見つからない

解決方法：GitHub Actions のチェックアウトアクションに submodules: recursive を追加します

問題：Sveltia CMS が読み込まれない

解決方法：

1. hugo でサイトを再ビルドします
2. public/ に /admin ディレクトリがあることを確認します
3. config.yml の構文を確認します
4. ブラウザーのコンソールにエラーがないか確認します

---

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

このチェックリストを使って、セットアップを確認します。

• Hugo Extended v0.149.0+ がインストールされている（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. ドキュメント化された9つのエラーと解決方法については、references/common-errors.md を確認してください
2. セットアップの全手順を確認してください
3. 公式ドキュメントを確認してください：https://gohugo.io/documentation/
4. Hugo Extended がインストールされていることを確認してください（最もよくある問題です）

---

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