はじめに

「WordPressは重い。でも静的HTMLは管理が大変…」

その悩み、Hugoが解決する。

Hugoは世界最速の静的サイトジェネレーター。Go言語で書かれ、数千ページのサイトでも1秒以下でビルドできる。

この記事では、Hugoの全体像を構造的に解説する。

Hugoとは

静的サイトジェネレーター（SSG）の位置づけ

    flowchart LR
    subgraph Traditional["従来型 CMS"]
        DB[(データベース)]
        PHP[PHP/Ruby]
        Server[サーバー]
        DB --> PHP --> Server
    end

    subgraph SSG["静的サイトジェネレーター"]
        MD[Markdown]
        Build[ビルド]
        HTML[静的HTML]
        CDN[CDN配信]
        MD --> Build --> HTML --> CDN
    end

    User((ユーザー))
    User --> Server
    User --> CDN

    style SSG fill:#e8f5e9,stroke:#2e7d32
    style Traditional fill:#fff3e0,stroke:#f57c00

主要SSGの比較

項目 Hugo Next.js Gatsby Jekyll
言語 Go JavaScript JavaScript Ruby
ビルド速度 ⚡ 最速 中速 遅い 遅い
学習コスト 低〜中 高 高 低
依存関係 なし Node.js Node.js Ruby
用途 ブログ・ドキュメント Webアプリ Webアプリ ブログ

Hugoの強み：依存関係なし、単一バイナリ、圧倒的なビルド速度

ディレクトリ構造

Hugoプロジェクトの設計思想を理解することが最重要。

全体構造

    graph TB
    subgraph Root["📁 プロジェクトルート"]
        Config["📄 hugo.toml<br/>サイト設定"]

        subgraph Content["📁 content/<br/>コンテンツ（Markdown）"]
            Posts["📁 posts/"]
            About["📄 about.md"]
        end

        subgraph Layouts["📁 layouts/<br/>テンプレート上書き"]
            Partials["📁 partials/"]
            Shortcodes["📁 shortcodes/"]
        end

        subgraph Static["📁 static/<br/>静的ファイル"]
            Images["📁 images/"]
            CSS["📁 css/"]
        end

        subgraph Themes["📁 themes/<br/>テーマ"]
            PaperMod["📁 PaperMod/"]
        end

        subgraph Assets["📁 assets/<br/>処理対象リソース"]
            SCSS["📄 *.scss"]
            JS["📄 *.js"]
        end

        Public["📁 public/<br/>ビルド出力"]
    end

    Config --> Content
    Content --> Public
    Layouts --> Public
    Static --> Public
    Themes --> Public
    Assets --> Public

    style Root fill:#f5f5f5
    style Content fill:#e3f2fd
    style Layouts fill:#fff3e0
    style Static fill:#e8f5e9
    style Themes fill:#fce4ec
    style Assets fill:#f3e5f5
    style Public fill:#e0e0e0

各ディレクトリの役割

    my-site/
├── hugo.toml          # サイト設定（必須）
├── content/           # Markdownコンテンツ
│   ├── _index.md      # セクションのトップページ
│   ├── posts/         # ブログ記事
│   │   ├── _index.md  # /posts/ のリストページ
│   │   ├── first.md   # /posts/first/
│   │   └── second.md  # /posts/second/
│   └── about.md       # /about/
├── layouts/           # テンプレート上書き
│   ├── _default/      # デフォルトテンプレート
│   ├── partials/      # 部品テンプレート
│   └── shortcodes/    # ショートコード
├── static/            # そのままコピーされる
│   └── images/        # /images/ として配信
├── assets/            # Hugo Pipesで処理
│   └── css/           # SCSS→CSS変換など
├── themes/            # テーマ（Git submodule推奨）
├── data/              # データファイル（YAML/JSON/TOML）
├── i18n/              # 多言語対応
└── public/            # ビルド出力（.gitignore推奨）

コンテンツ管理

Front Matter（記事メタデータ）

すべてのMarkdownファイルはFront Matterで始まる。

    ---
title: "記事タイトル"
date: 2026-01-17
draft: false              # true で下書き
tags: ["Hugo", "SSG"]
categories: ["開発ツール"]
description: "記事の説明"
weight: 10                # 並び順（小さいほど先）
slug: "custom-url"        # URLを上書き
aliases:                  # 旧URLからリダイレクト
  - /old-url/
cover:
  image: "images/cover.jpg"
  alt: "カバー画像"
---

本文はここから...

コンテンツの階層構造

    graph TB
    subgraph URL["URL構造"]
        Root2["/"]
        Posts2["/posts/"]
        Post1["/posts/first/"]
        About2["/about/"]
    end

    subgraph Files["ファイル構造"]
        ContentDir["content/"]
        Index["_index.md"]
        PostsDir["posts/"]
        PostsIndex["posts/_index.md"]
        First["posts/first.md"]
        AboutMD["about.md"]
    end

    ContentDir --> Index --> Root2
    ContentDir --> PostsDir --> PostsIndex --> Posts2
    PostsDir --> First --> Post1
    ContentDir --> AboutMD --> About2

    style URL fill:#e8f5e9
    style Files fill:#e3f2fd

ページの種類

種類 ファイル 用途
Single Page content/about.md 単体ページ
List Page content/posts/_index.md 一覧ページ
Home Page content/_index.md トップページ
Taxonomy 自動生成 タグ・カテゴリ一覧

テンプレートシステム

テンプレートの優先順位

Hugoは最も具体的なテンプレートを優先する。

    flowchart TB
    subgraph Lookup["テンプレート探索順序"]
        direction TB
        L1["1. layouts/posts/single.html"]
        L2["2. layouts/_default/single.html"]
        L3["3. themes/PaperMod/layouts/posts/single.html"]
        L4["4. themes/PaperMod/layouts/_default/single.html"]
    end

    L1 -->|なければ| L2
    L2 -->|なければ| L3
    L3 -->|なければ| L4

    style L1 fill:#c8e6c9
    style L2 fill:#fff9c4
    style L3 fill:#ffccbc
    style L4 fill:#f5f5f5

基本テンプレート構文

    <!-- 変数出力 -->
{{ .Title }}
{{ .Content }}
{{ .Date.Format "2006-01-02" }}

<!-- 条件分岐 -->
{{ if .Params.draft }}
  <span>下書き</span>
{{ end }}

<!-- ループ -->
{{ range .Pages }}
  <li>{{ .Title }}</li>
{{ end }}

<!-- パーシャル（部品）読み込み -->
{{ partial "header.html" . }}

<!-- with（nilチェック付き代入） -->
{{ with .Params.author }}
  <p>著者: {{ . }}</p>
{{ end }}

主要な変数

    graph LR
    subgraph Page["ページ変数"]
        Title[".Title"]
        Content[".Content"]
        Date[".Date"]
        Params[".Params"]
        Permalink[".Permalink"]
    end

    subgraph Site["サイト変数"]
        SiteTitle[".Site.Title"]
        SiteParams[".Site.Params"]
        SitePages[".Site.Pages"]
        SiteMenus[".Site.Menus"]
    end

    subgraph Special["特殊変数"]
        Hugo[".Hugo.Version"]
        IsHome[".IsHome"]
        IsPage[".IsPage"]
    end

ショートコード

Markdown内で使える再利用可能な部品。

組み込みショートコード

    <!-- YouTube埋め込み -->
{{< youtube dQw4w9WgXcQ >}}

<!-- Twitter埋め込み -->
{{< twitter 123456789 >}}

<!-- Gist埋め込み -->
{{< gist username gist_id >}}

<!-- 図表 -->
{{< figure src="/images/photo.jpg" title="キャプション" >}}

カスタムショートコード

layouts/shortcodes/alert.html を作成：

    <div class="alert alert-{{ .Get 0 }}">
  {{ .Inner | markdownify }}
</div>

使い方：

    {{< alert "warning" >}}
これは警告メッセージです。
{{< /alert >}}

Hugo Pipes（アセット処理）

    flowchart LR
    subgraph Input["入力"]
        SCSS["assets/css/main.scss"]
        JS1["assets/js/app.js"]
    end

    subgraph Process["Hugo Pipes処理"]
        ToCSS["toCSS"]
        Minify["minify"]
        Fingerprint["fingerprint"]
        Bundle["resources.Concat"]
    end

    subgraph Output["出力"]
        CSS2["public/css/main.min.abc123.css"]
        JS2["public/js/bundle.min.def456.js"]
    end

    SCSS --> ToCSS --> Minify --> Fingerprint --> CSS2
    JS1 --> Bundle --> Minify --> JS2
  
    {{ $style := resources.Get "css/main.scss"
    | toCSS
    | minify
    | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

コマンドリファレンス

基本コマンド

    # 新規サイト作成
hugo new site my-site

# 新規記事作成
hugo new posts/my-first-post.md

# 開発サーバー起動（下書き含む）
hugo server -D

# 開発サーバー（ポート指定）
hugo server -D -p 3000

# 本番ビルド
hugo --minify

# 本番ビルド（baseURL指定）
hugo --minify --baseURL "https://example.com/"

便利なオプション

オプション 説明
-D 下書き（draft: true）を含める
--minify HTML/CSS/JSを圧縮
--gc 未使用キャッシュを削除
--cleanDestinationDir 出力先をクリーン
-e production 環境を指定
--templateMetrics テンプレート処理時間を表示

設定ファイル（hugo.toml）

基本設定

    baseURL = 'https://example.com/'
languageCode = 'ja'
title = 'My Site'
theme = 'PaperMod'

# ビルド設定
buildDrafts = false
buildFuture = false

# URL設定
relativeURLs = true
canonicalURLs = false

# パーマリンク設定
[permalinks]
  posts = '/:year/:month/:slug/'

# メニュー
[menu]
  [[menu.main]]
    identifier = "posts"
    name = "Posts"
    url = "/posts/"
    weight = 10

# パラメータ（テーマ設定など）
[params]
  author = "Your Name"
  description = "Site description"

# Markdown設定
[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true  # HTMLタグを許可
  [markup.highlight]
    style = "monokai"

環境別設定

    config/
├── _default/
│   ├── hugo.toml      # 共通設定
│   └── params.toml    # 共通パラメータ
├── development/
│   └── hugo.toml      # 開発環境用
└── production/
    └── hugo.toml      # 本番環境用

テーマのカスタマイズ

上書きの仕組み

    flowchart TB
    subgraph Priority["優先順位"]
        direction TB
        P1["1. layouts/ （プロジェクト）"]
        P2["2. themes/テーマ名/layouts/"]
    end

    subgraph Example["例：フッターを上書き"]
        Original["themes/PaperMod/layouts/partials/footer.html"]
        Override["layouts/partials/footer.html ← これを作成"]
    end

    P1 --> P2
    Override -.->|上書き| Original

    style P1 fill:#c8e6c9
    style Override fill:#c8e6c9

カスタマイズ手順

  1. 上書きしたいファイルを特定
  2. 同じパスで layouts/ にコピー
  3. 編集
    # 例：フッターをカスタマイズ
cp themes/PaperMod/layouts/partials/footer.html layouts/partials/

デプロイ

主要なホスティングサービス

    flowchart LR
    subgraph Build["ビルド"]
        Hugo[Hugo]
        Public["public/"]
        Hugo --> Public
    end

    subgraph Deploy["デプロイ先"]
        CF["Cloudflare Pages"]
        GH["GitHub Pages"]
        Netlify["Netlify"]
        Vercel["Vercel"]
    end

    Public --> CF
    Public --> GH
    Public --> Netlify
    Public --> Vercel

Cloudflare Pages設定例

項目 値
Build command hugo --minify
Build output directory public
Environment variable HUGO_VERSION = 0.146.0

GitHub Actions例

    name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

よくあるトラブル

1. CSSが当たらない

    flowchart TB
    Problem["CSSが当たらない"]

    Check1{"baseURLは正しい？"}
    Check2{"relativeURLs = true?"}
    Check3{"テーマのsubmoduleは？"}

    Problem --> Check1
    Check1 -->|No| Fix1["hugo.tomlのbaseURLを修正"]
    Check1 -->|Yes| Check2
    Check2 -->|No| Fix2["relativeURLs = true を追加"]
    Check2 -->|Yes| Check3
    Check3 -->|No| Fix3["git submodule update --init"]

2. 記事が表示されない

原因 解決策
draft: true hugo server -D または draft: false
未来の日付 hugo server -F または日付を修正
Front Matter構文エラー YAML構文を確認

3. ビルドエラー

    # キャッシュクリア
hugo --gc --cleanDestinationDir

# 詳細ログ
hugo --verbose --debug

まとめ

    mindmap
  root((Hugo))
    コンテンツ
      Markdown
      Front Matter
      ショートコード
    テンプレート
      Go Template
      Partials
      優先順位
    設定
      hugo.toml
      環境別設定
    アセット
      Hugo Pipes
      SCSS
      Minify
    デプロイ
      Cloudflare Pages
      GitHub Pages
      Netlify

Hugoはシンプルさと高速性を両立した静的サイトジェネレーター。

  • ディレクトリ構造を理解すれば迷わない
  • テンプレートの優先順位を把握すればカスタマイズは自在
  • Git + CDNで運用すれば無料でスケーラブル

まずは hugo new site から始めよう。

参考リンク