Claude CodeでHugoサイトを作る — インストールからテーマ導入まで

Hugoとは — Claude Codeで静的サイトを作る流れ

Hugoは静的サイトジェネレーターです。Markdownで書いた記事をビルドすると、サーバー側の処理なしで配信できるHTMLサイト一式が生成されます。多言語化とリンク切れ検査まで含めた構成は、DocusaurusのドキュメントサイトでのClaude Code活用で扱っています。

Claude Codeのターミナル操作とファイル編集の機能を使うと、プロジェクトの作成からテーマ導入、コンテンツ追加、ビルドまでの一連の作業を、コマンドを逐一調べずに進められます。実行するコマンド自体はHugo公式のQuick startと同じで、Claude Codeが担うのはそれらを状況に応じて実行し、設定ファイルを編集する部分です。ビルドが生成するのは素のHTML・CSS・JavaScriptだけなので、出来上がったファイル一式は静的ファイルを配信できるホスティング先であれば基本的にどこへでも配置できます。

本記事で扱うのはターミナルで動くClaude Code CLIの操作です。コマンドの出力は、Hugo v0.167.0とClaude Code v2.1.287を使い、空のディレクトリで実際に実行した結果です。

前提条件

このチュートリアルを進めるには、次の環境が必要です。

• Hugo(標準版・extended版のどちらでも可)のv0.158.0以降
• Git
• ターミナル操作の基本的な知識
• Claude Codeの利用アカウント(Pro・Max・Team・Enterpriseのいずれかのサブスクリプション、またはConsoleアカウント)

Hugo本体のインストール方法はOSやパッケージマネージャーによって異なります。本記事では hugo コマンドがすでに使える状態を前提に、以降の手順を進めます。

ステップ1: Claude Codeをインストールしてログインする

macOS・Linux・WSLでは、次のコマンド1行でClaude Codeのネイティブインストーラーが導入できます。

curl -fsSL https://claude.ai/install.sh | bash

Windowsの場合は、PowerShellで次のコマンドを実行します。

irm https://claude.ai/install.ps1 | iex

インストール後は claude --version でバージョンを確認できます。OS別の詳しい手順やHomebrew・WinGet経由の導入方法は、Claude Code installガイドにまとめています。

作業用のディレクトリを作ってから claude コマンドで対話セッションを開始します。初回はブラウザでのログインを求められます。

mkdir hugo-work && cd hugo-work
claude

ステップ2: サイトの雛形とテーマ導入をClaude Codeに任せる

Claude Codeのセッション内で、作りたいサイトの内容を自然言語で伝えます。

Hugoで新しいプロジェクトをmysiteという名前で作成して、Anankeテーマをgit submoduleとして追加してください

Claude Codeはプロジェクトファイルを自分で確認しながら作業を進めるため、事前にディレクトリ構成を説明する必要はありません。人が同じ作業をターミナルで直接行う場合、同じ作業を手で行うコマンド列は次のとおりです。

hugo new project mysite
cd mysite
git init
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml

hugo new projectは--format yamlや--format jsonを付けると、設定ファイルをTOML以外の形式で作ります(既定はtoml)。空でないディレクトリに作るときは-f(--force)を付けます。

テーマを入れ忘れたビルドは何を出力するか

テーマを入れる前にビルドすると、エラーにはならず、警告だけが出ます。mysiteでgit submodule addを実行する前にhugoを実行した結果は次のとおりです。

WARN  found no layout file for "html" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "section": ...
WARN  found no layout file for "html" for kind "taxonomy": ...
 
 Pages            │  5

逆に、hugo.tomlにtheme = 'ananke'と書いたのにthemes/anankeが空(サブモジュールを取得していない状態)だと、ビルドは警告ではなくエラーで止まります。出力されたのは次の1行です(パスは省略)。

ERROR failed to load modules: module "ananke" not found in ".../themes/ananke"; either add it as a Hugo Module or store it in ".../themes".: module does not exist

ステップ3: 開発サーバーで見た目を確認する

テーマの導入が終わったら、開発サーバーを起動して見た目を確認します。

hugo server

コマンドを実行すると、ターミナルにプレビュー用のURLが表示されます。ブラウザでそのURLを開くと、Anankeテーマが適用された状態のサイトを確認できます。

hugo serverはファイルの変更を検知して自動で再ビルドします。記事のtitleを書き換えて保存したところ、Change detected, rebuilding site (#1)と出力され、プレビューのページタイトルも書き換わりました。サーバーを起動したまま、続くステップの作業を進められます。停止するには、ターミナルでCtrl + Cを押します。

ステップ4: コンテンツを追加する

記事を1本追加してみます。Claude Codeに次のように依頼します。

content/posts配下に、my-first-postという名前で新しい投稿を作成してください

同じ作業を手で行うコマンドは次のとおりです。

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

生成されるファイルには、日付・draftフラグ・タイトルを含むフロントマターが自動で挿入されます。v0.167.0で実際にできたファイルの中身は次のとおりです。

+++
date = '2026-10-03T21:26:14+09:00'
draft = true
title = 'My First Post'
+++

公式のQuick startの例ではtitleが先頭ですが、プロジェクトのarchetypes/default.mdが日付・draft・titleの順に書いているため、実際の並びは異なります。titleはファイル名のハイフンを空白に置き換え、単語の先頭を大文字にした値です。日本語のタイトルにしたいときは、この行を書き換えます。

draftがtrueのままだと、Hugoはビルド時にこの記事を出力しません。ビルドしてpublicを調べると、結果は次のとおりでした。

下書きがどこに残っているかは、hugo list draftsで調べられます。出力はCSV形式で、パス・title・日付・公開予定日時・draftの値・公開時のURLなどの列が並びます。下書きの状態を開発サーバーで確認するには、次のオプションを付けて起動します。

hugo server -D

本文はCommonMark仕様に沿ったMarkdownで書けます。太字や斜体、リンクといった基本的な記法がそのまま使えます。公開する準備ができたら、フロントマターのdraftをfalseに変更します。この値の書き換えも、Claude Codeに対象ファイルとキーを伝えれば代わりに編集してもらえます。

ステップ5: 設定を仕上げてビルドする

公開前に、hugo.tomlの主要な項目を実際の値に更新します。

baseURL = 'https://example.org/'
locale = 'ja-jp'
title = 'My New Hugo Project'
theme = 'ananke'

baseURLはプロトコルから始まり、末尾をスラッシュで終える必要があります。localeとtitleも、公開するサイトの言語やサイト名に合わせて書き換えます。Claude Codeにこれらの値を伝えれば、hugo.tomlの該当行を書き換えてもらえます。

値を変えたときの出力を、Ananke導入済みのプロジェクトで比べました。

baseURLのパス部分(/blog/)は、CSSの参照先やsitemapのURLに反映されます。公開先がサブディレクトリ(https://ユーザー名.github.io/hugo-demo/のような形)なら、パスまで含めて指定します。そのままhugo serverを起動すると、プレビューのURLもパス付き(例: http://localhost:1313/hugo-demo/)で表示されます。パスなしのhttp://localhost:1313/を開くと、404が返りました。

ビルド時だけ値を差し替えたいときは、-b(--baseURL)を付けます。hugo -b https://ユーザー名.github.io/hugo-demo/と実行すると、hugo.tomlを書き換えなくても変わります。CSSの参照先は/hugo-demo/ananke/css/…になりました。

設定を反映したら、ビルド用のコマンドを実行します。

hugo

このコマンドは、HTMLファイルや画像・CSS・JavaScriptなどのビルド成果物一式を、プロジェクト直下のpublicディレクトリに出力します。ここまでの手順は公開用ファイルを生成する作業(ビルド)であり、実際にインターネット上へ配置するデプロイとは別の作業です。

ビルド後にGitの状態を見ると、public/と.hugo_build.lockが未追跡のファイルとして現れます。成果物をリポジトリに含めるかどうかは、公開先の方式で決めます。Claude Codeにコミットを任せる場合は、先に.gitignoreの方針を伝えておくと、意図しないファイルが混ざりません。

Claude Codeに任せる範囲と自分で確認する範囲

Auto modeで多くのコマンドが確認なしに進むとしても、本文の中身とbaseURLのような本番設定は、人が最終確認する前提で任せます。

毎回の指示を減らすCLAUDE.mdの書き方

CLAUDE.mdは、Claudeがセッションの開始時に読む指示ファイルです。ここまでの検証で分かったHugo固有の落とし穴を書いておくと、次のセッションで同じ確認をやり直さずに済みます。プロジェクトのルートに置く例です。

# mysite(Hugo + Ananke)
 
- プレビュー: `hugo server -D`(下書きを含む)
- ビルド: `hugo`。出力先はpublic/で、直接編集しない
- 新規投稿: `hugo new content content/posts/<名前>.md`(draft = true で作られる)
- テーマはthemes/ananke(git submodule)。themes/配下は編集しない
- hugo.tomlのbaseURLは公開先のURLでパスを含む。変更前に必ず確認を求める
- 公開前にdraftが残っていないか`hugo list drafts`で確認する

themes/anankeはサブモジュール(取得元は別のリポジトリ)なので、テーマ側のファイルを書き換えない指示を入れています。名前の付け方や記事の書き方の決まりまで書き足したいときは、CLAUDE.mdを実用に引き上げる10のパターンが参考になります。複数ページにまたがるサイト構成を仕様から組み立てたい場合は、cc-sddによる仕様駆動開発も選択肢です。

よくあるつまずき

• Windowsでコマンドが失敗する: コマンドプロンプトや従来のWindows PowerShellを使っていると、Hugo公式が案内する操作の一部が動きません。PowerShell(pwsh)か、WSL・Git Bashなどのターミナルを使います
• 下書きが開発サーバーに表示されない: フロントマターのdraftがtrueのままだと、既定のhugo serverでは表示されません。hugo server -Dで起動するか、draftをfalseに変更します
• テーマを指定したのにビルドが止まる: themes/anankeが空だとmodule "ananke" not foundで止まります。git submodule addが成功したか、themes/anankeにファイルが入っているかを確認します
• ビルド後にCSSや画像が読み込まれない: baseURLのパス部分と、実際の配置先のパスが合っているかを確認します。サブディレクトリに置くなら、baseURLにそのパスまで含めます
• プレビューのURLが404になる: baseURLにパスを含めている場合、hugo serverはそのパスの下で動きます。ターミナルに表示されたURLをそのまま開きます

上記で解決しない場合は、Hugo公式フォーラムに2万件を超える質問と回答が蓄積されています。似た症状の事例が既に投稿されていることも多く、検索するだけで解決することがあります。

まとめ

Claude Codeに任せた作業のあとでも、publicの中身を見れば、テーマ・draft・baseURLのずれは公開前に気づけます。

小さなプロジェクトで一連の流れを試し、問題がなければ本番のbaseURLに進む順序が安全です。