hugo-theme

Hugo テーマ開発

Hugo CMS テーマ開発の中級から上級向けパターンです。タスクに関連するリファレンスファイルを読み込んでください。

リファレンスファイル

トピック	Hugo の最小バージョン	読み込むタイミング	ファイル
テンプレートアーキテクチャ	v0.120+	ブロックを使ったベーステンプレートの設定、テンプレートの検索順序（kind/layout/type/section）の理解、パーシャルの作成、パーシャルデコレーター（v0.154+）の使用、またはショートコードの基本を扱う場合	references/template-architecture.md
アセットパイプライン	v0.161+	Tailwind CSS v4（css.TailwindCSS）または v3（PostCSS）の統合、Hugo Pipes による SCSS/JS のバンドル、フィンガープリントと SRI の設定、srcset を使ったレスポンシブ画像の構築、またはページ／グローバル／リモートリソースの処理を行う場合	references/asset-pipeline.md
ショートコードとレンダーフック	v0.112+	複雑なネストされたショートコード、raw HTML ショートコード、ショートコード内での Markdown レンダリング、リンク／画像／見出し／コードブロック用のカスタムレンダーフック、または言語別のコードブロックレンダリング（Mermaid など）が必要な場合	references/shortcodes-and-hooks.md
コンテンツの構成と i18n	v0.126+	リーフバンドルとブランチバンドル、ヘッドレスバンドル、カバー画像、カスタムタクソノミー、コンテンツアダプター（v0.126+、動的ページ）、セクション別レイアウト、アーキタイプ、または国際化（翻訳テーブル、多言語）を扱う場合	references/content-and-i18n.md
カバー画像	v0.120+	記事にカバー／ヒーロー画像を追加する、ページバンドルのリソースとフロントマターのパスの両方に対応する、レスポンシブな srcset を生成する、またはカバー画像がない場合を適切に処理する必要がある場合	references/cover-images.md
モジュールとパフォーマンス	v0.109+	Hugo Modules（init、import、vendor、workspace）を使用する、マウント設定を使ってテーマコンポーネントを構築する、partialCached でビルド速度を最適化する、キャッシュ TTL を設定する、または設定駆動型のテーマ設定（params、cascade）を使用する場合	references/modules-and-performance.md
デザイン、UX、アクセシビリティ	v0.120+	タイポグラフィシステム、アクセシブルなカラーパレット、デザイントークン、セマンティック HTML ランドマーク、ARIA パターン、キーボードナビゲーション、アクセシブルなフォーム、コンテンツ優先のレイアウト、レスポンシブナビゲーション、エンゲージメントパターン（読書の進捗、ダークモード切り替え、共有）、Core Web Vitals の最適化、コンテナクエリ、:has() セレクター、またはテスト／QA の自動化（axe-core、Lighthouse CI、ビジュアルリグレッション）が必要な場合	references/design-accessibility.md
SEO、出力形式、CI/CD	v0.120+	JSON-LD 構造化データ、Open Graph / Twitter Cards、カスタム出力形式（JSON、AMP）、サイトマップのカスタマイズ、またはテーマ向け CI/CD パイプライン（GitHub Actions、テスト、デプロイ）が必要な場合	references/seo-outputs-testing.md

クイックスタート

{{/* Minimal theme baseof.html — start here */}}
<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ block "title" . }}{{ .Site.Title }}{{ end }}</title>
  {{ block "styles" . }}{{ end }}
</head>
<body>
  {{ block "header" . }}{{ partial "header.html" . }}{{ end }}
  <main>{{ block "main" . }}{{ end }}</main>
  {{ block "footer" . }}{{ partial "footer.html" . }}{{ end }}
  {{ block "scripts" . }}{{ end }}
</body>
</html>

ステップごとに進める：新しいテーマの初期設定

# 1. Create the theme directory
mkdir -p themes/my-theme/{layouts/{_default,_markup,partials,shortcodes},assets/{scss,css,js}}

# 2. Create baseof.html (use the template above) defining blocks:
#    title, styles, header, main, footer, scripts

# 3. Create partials for reusable components
#    layouts/partials/header.html, footer.html, css.html

# 4. Set up your asset pipeline
#    - SCSS  → assets/scss/main.scss + toCSS partial
#    - Tailwind  → assets/css/main.css + css.TailwindCSS partial
#    - JS  → assets/js/main.js + js.Build

# 5. Configure hugo.yaml
#    theme: my-theme
#    See the reference file for your chosen CSS approach.

# 6. Build and verify
hugo --gc
ls public/ | head

ヒント： プロジェクトレベルの layouts/ はテーマの layouts/ を上書きします。テーマを単独でテストする場合は、上書きが必要になるまでプロジェクトの layouts/ ディレクトリを空にしておいてください。

よくある落とし穴

• SCSS には Hugo extended 版が必要です。 macOS/Homebrew のデフォルトの Hugo ビルドは extended 版ではありません。hugo version | grep extended で確認してください。
• Tailwind v4 では PostCSS ではなく css.TailwindCSS を使用します。 v4 では postcss-cli をインストールしないでください。代わりにネイティブのパイプを直接使用します。Tailwind v3 では引き続き PostCSS パイプラインが必要です。
• partialCached は定数以外の引数を使うと古い結果を返します。 バリアント文字列（.Section、page.RelPermalink）は呼び出し元ごとに一意である必要があります。セクション名が重複すると、古い結果が返されます。
• hugo new はアーキタイプのディレクトリ構造に従います。 フラットファイルではなくページバンドルを作成するには、アーキタイプを archetypes/<section>/index.md に配置してください。
• resources.Get は static/ ではなく assets/ を参照します。 static/ 内のファイルはそのままコピーされ、Hugo Pipes では処理されません。Pipes を通すファイルには assets/ を使用してください。
• コンテンツアダプターテンプレートは、必ず _content.gotmpl という名前にする必要があります。 同じディレクトリに _content.gotmpl がある場合、通常の .md ファイルは無視されます。
• レンダーフックテンプレートは _markup/ サブディレクトリに配置します。 _default/ 直下ではありません。layouts/_default/_markup/render-link.html またはセクション固有の layouts/<type>/_markup/ に配置する必要があります。
• パーシャル内の block は、ページテンプレート内の define と競合します。 パーシャル内（例：head.html）の {{ block "title" . }} は、ページテンプレート内（例：single.html）の {{ define "title" }} と同じ Go テンプレートの名前空間を使用します。両方がレンダーツリーに存在すると、Hugo は multiple definition of template "title" というエラーを返します。解決方法：パーシャル内では block の代わりに、ページ変数（.Title、.Site.Title）を直接使用してください。block は baseof.html のシェル専用にしてください。