🧭 はじめに：この記事で理解できること
Hugo は高速で柔軟な静的サイトジェネレーターですが、フォルダ構造が分かりにくいと感じる初心者は多いです。
この記事では、以下のことを丁寧に解説します。
- Hugo プロジェクトのフォルダ構造の全体像
- 各ディレクトリの役割
- PaperMod を使う場合の注意点
- GitHub Pages で運用する際に理解しておくべきポイント
補足
Hugo のフォルダ構造は「必要なものだけ作ればよい」仕組みです。最初から全部覚える必要はありません。
🗂️ 全体構造：Hugo プロジェクトの基本フォルダ
まずは、Hugo プロジェクトの典型的な構造を見てみましょう。
# Hugo プロジェクトの基本構造（例）
.
├─ config/ または hugo.yaml # サイト設定
├─ content/ # 記事（Markdown）
├─ layouts/ # テンプレート（上書き用）
├─ static/ # 静的ファイル（画像・HTMLなど）
├─ assets/ # SCSS/JS（Hugo Pipes）
├─ themes/ # PaperModなどテーマ
├─ archetypes/ # 記事テンプレート
└─ public/ # ビルド後の出力（自動生成）
注意
public/は Hugo がビルド時に自動生成するため、手動で編集しないようにしましょう。
📁 1. config/（または hugo.yaml）：サイト全体の設定
Hugo の設定は config ディレクトリまたは hugo.yaml に記述します。
PaperMod を使う場合、hugo.yaml で管理するのが一般的です。
# hugo.yaml の例
baseURL: "https://username.github.io/repository-name/"
title: "My Hugo Blog"
theme: "PaperMod"
補足
GitHub Pages のプロジェクトサイトでは、baseURLの末尾に/repository-name/が必要です。
📝 2. content/：記事（Markdown）を置く場所
ブログ記事はすべて content/ に配置します。
PaperMod の場合、一般的には以下のような構造になります。
content/
├─ posts/
│ ├─ first-post.md
│ └─ second-post.md
└─ about.md
ポイント
posts/は任意のフォルダ名で OK。PaperMod の設定で変更できます。
🎨 3. layouts/：テンプレートをカスタマイズする場所
テーマ（PaperMod）のテンプレートを上書きしたい場合に使います。
例：layouts/partials/ にファイルを置くと、テーマの同名ファイルより優先されます。
layouts/
└─ partials/
└─ head.html # PaperMod の head を上書き
注意
テーマを直接編集するとアップデート時に上書きされるため、layouts/ で上書きするのが正しい方法です。
🖼️ 4. static/：静的ファイル（画像・HTML・JS）
static/ に置いたファイルは、ビルド時に そのまま公開ディレクトリへコピーされます。
例：Search Console の HTML ファイルを置く場合
static/
└─ googleXXXXXXXXXXXX.html
補足
公開後はhttps://username.github.io/repository-name/googleXXXXXXXXXXXX.htmlでアクセスできます。
🧵 5. assets/：Hugo Pipes（SCSS/JS）用
PaperMod では SCSS を使うため、カスタム CSS を追加する場合は assets/ を使います。
assets/
└─ css/
└─ custom.scss
ポイント
static/css/と混同しやすいですが、assets はビルド処理されるファイルです。
🧩 6. themes/：PaperMod などテーマを配置
テーマを Git submodule で管理する場合はここに入ります。
themes/
└─ PaperMod/
注意
テーマを直接編集しないこと。カスタマイズは layouts/ または assets/ で行います。
📦 7. archetypes/：記事テンプレート
hugo new コマンドで記事を作るときのテンプレートです。
archetypes/
└─ default.md
補足
PaperMod では front matter を自分好みに整えるために編集することが多いです。
🚀 8. public/：ビルド後の出力（GitHub Pages で公開）
hugo コマンドを実行すると生成されるフォルダです。
GitHub Pages の gh-pages ブランチにデプロイする場合、この public/ の中身を push します。
注意
public/は自動生成のため、Git 管理しない運用も一般的です（CI/CD 推奨）。
🧯 よくあるつまずきポイント（チェックリスト）
-
baseURLが GitHub Pages の URL と一致しているか -
static/とassets/の役割を混同していないか - テーマを直接編集していないか
-
layouts/の上書きルールを理解しているか -
public/を手動で編集していないか
📚 参考リンク
- Hugo 公式ドキュメント
- Configuration: https://gohugo.io/getting-started/configuration/
- Directory Structure: https://gohugo.io/getting-started/directory-structure/
- Static Files: https://gohugo.io/content-management/static-files/
- PaperMod 公式
🔧 拡張案（次にやると良いこと）
- PaperMod の head.html をカスタマイズして SEO 最適化
- SCSS を使ったカスタムデザインの追加（assets/css/custom.scss）
- GitHub Actions で自動ビルド＆デプロイを構築
- 構造化データ（JSON-LD）を layouts/ に追加
- 画像最適化（WebP 生成・srcset 対応）で Core Web Vitals 改善
✅ まとめ
- Hugo のフォルダ構造は「必要なものだけ使う」柔軟な仕組み
- content・layouts・static の違いを理解すると運用が一気に楽になる
- PaperMod のカスタマイズは layouts/ と assets/ が中心
- GitHub Pages 運用では baseURL と public/ の扱いが重要