こんにちは、たひです。

Hugo と ClaudeCode を使って、技術ブログを立ち上げました。 学生時代に React でポートフォリオを作っていたんですが、メンテナンスも構造の理解も追いついておらず新しくサイトを立ち上げることにしました。FFやClaudeには Hugo を勧められたのでそちらに移行しました。 ClaudeCode の力を借りながら1日で構築できたので、その過程を紹介します。

なぜHugoを選んだのか？ClaudeCodeとの親和性

以前のポートフォリオからの移行

以前は React + TypeScript でポートフォリオサイトを作っていました。

技術の勉強にはなったんですが、ブログとして使うには正直使いづらかったです。

React vs Hugo の違い

React（SPA）の特徴

• クライアント側でDOMを動的に生成
• バンドルサイズが大きい（数百KB）
• 初回表示まで白い画面が続く
• インタラクティブなUIは得意

Hugo（静的サイトジェネレータ）の特徴

• ビルド時にHTMLを事前生成
• 超軽量（JavaScriptなしでも動作）
• HTMLを直接配信するので即座に表示
• SEOに強い

Reactで困った点

正直、ブログには React は過剰でした。

• ビルド時間: 変更のたびに数十秒待つ必要がある（Hugoは1秒以下）
• 記事管理: JSXコンポーネント内にコンテンツを書くのが面倒（Hugoは純粋なMarkdown）
• SEO対策: SSRやSSGの設定が必要（Hugoは標準対応）
• メンテナンス: npm依存パッケージの更新が頻繁（Hugoはバイナリ単体で動作）

技術的な実験には良かったんですが、記事を継続的に書くには不向きだなと。

それで静的サイトジェネレータへの移行を決めました。

なぜHugoにしたのか

WordPress、Next.js、Hugoなど色々検討しました。

最終的にHugoを選んだ理由は3つです。

1. ビルド速度の圧倒的な速さ

Go言語で書かれているので、数百ページでも数秒でビルドが完了します。

記事を書いてすぐにプレビューできるので、執筆体験がめちゃくちゃ快適なんですよね。

2. シンプルなMarkdownベースの執筆

記事はすべてMarkdownファイルで管理できます。

Gitでバージョン管理もしやすいですし、組み込みエンジニアとしてテキストベースの環境には慣れているので相性が良かったです。

3. 静的サイトのセキュリティとパフォーマンス

データベースが不要なのでセキュリティリスクが低いです。

CDNで配信すれば超高速にページが表示されますし、サーバー管理の手間もゼロ。

ClaudeCodeとの相性が抜群だった

Hugoの構築過程で、ClaudeCodeが特に力を発揮してくれました。

テンプレート構造の理解

Hugoのディレクトリ構造やテンプレート階層を即座に解説してくれるんです。

「このファイルをどこに置けばいいか」といった疑問にも的確に回答してくれました。

設定ファイルの最適化

hugo.toml の適切なパラメータ設定を提案してくれたり、SEOに必要な設定も網羅的にアドバイスしてくれます。

トラブルシューティングの速さ

エラーメッセージから原因を即座に特定して、解決策をコード例付きで提示してくれました。

Hugoのドキュメントを読みながら進めるより、ClaudeCodeに質問しながら進める方が圧倒的に速かったです。

初めてのHugoでも1日でブログを立ち上げられました。

Hugo Theme Stackのオーバーライドに苦戦

テーマ選定とカスタマイズの必要性

Hugo Theme Stack は、モダンでレスポンシブな優れたテーマです。

ただ、デフォルトのままだと自分のスタイルに合わなかったので、カスタマイズが必要でした。

オーバーライドの仕組みで苦労した点

1. テーマのオーバーライド階層の理解

Hugoでは layouts/ ディレクトリに同名ファイルを配置すると、テーマのファイルを上書きできます。

でも、どのファイルをオーバーライドすればいいのか分からないんですよね。

テーマの構造を理解するのに時間がかかりましたし、一部だけ変更したいのにファイル全体をコピーする必要があって面倒でした。

実例：日付表示のカスタマイズ

記事の公開日と更新日を表示したかったんですが、デフォルトでは公開日のみ。

layouts/partials/article/components/details.html をオーバーライドして実装しました。

1
2
3
4
5
6
7
8
9

<!-- 更新日の表示を追加 -->
{{ if $showLastmod }}
    <div>
        {{ partial "helper/icon" "refresh" }}
        <time class="article-time--updated">
            {{ .Lastmod | time.Format "2006/01/02" }}に更新
        </time>
    </div>
{{ end }}

2. CSSのカスタマイズ

テーマのSCSSをオーバーライドして独自のカラーテーマを設定しました。

• ダークモード対応のカラー変数を調整
• アイコンと文字の間隔を調整（デフォルトでは広すぎる）
• ピン留め記事のバッジカラーをカスタマイズ

例えば、日付表示のアイコンと文字の間隔が広すぎたので調整しました。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// assets/scss/custom.scss
.article-time {
    div {
        display: flex;
        align-items: center;
        gap: 0.35em; /* アイコンと文字の間隔を文字サイズに合わせる */

        svg {
            width: 16px;  /* デフォルトの20pxから縮小 */
            height: 16px;
            transform: translateY(0.5px); /* 微調整 */
        }
    }
}

3. パーシャルテンプレートの活用

ファビコンが表示されない問題にも直面しました。

layouts/partials/head/favicon.html を新規作成して解決しました。

1
2

<link rel="icon" type="image/x-icon" href="{{ .Site.BaseURL }}favicon.ico">
<link rel="shortcut icon" type="image/x-icon" href="{{ .Site.BaseURL }}favicon.ico">

ClaudeCodeの助けで、テーマの構造を理解しながらカスタマイズを進められました。

ただ、初見では難易度が高いと感じましたね。

Cloudflareでのデプロイとドメイン取得

Cloudflare Pagesを選んだ理由

ホスティングサービスは、Netlify、Vercel、GitHub Pagesなど選択肢がありますが、Cloudflare Pagesを選びました。

決め手となったポイントは以下の通りです。

1. 無料枠が充実 - 無制限のビルド回数とトラフィック
2. グローバルCDN標準装備 - 世界中で高速表示
3. 独自ドメインの設定が簡単 - Cloudflareでドメイン管理も一元化
4. 自動デプロイ - GitHubにプッシュすれば自動ビルド＆デプロイ

無料でここまで使えるのは本当にありがたいです。

デプロイの手順

1. GitHubリポジトリの準備

1
2
3
4
5

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/repo.git
git push -u origin main

2. Cloudflare Pagesでプロジェクト作成

Cloudflareのダッシュボードから「Pages」を選択して、GitHubアカウントを連携します。

リポジトリを選択したら、ビルド設定を行います。

• ビルドコマンド: hugo --minify
• 出力ディレクトリ: public
• 環境変数: HUGO_VERSION=0.152.2

3. 独自ドメインの取得と設定

Cloudflareでドメインを取得して、Pagesに紐付けました。

• Cloudflare Registrarでドメイン購入（.dev ドメインを取得）
• DNS設定は自動で完了
• HTTPS証明書も自動発行

めちゃくちゃ楽でした。

注意したポイント

• Hugoのバージョンを環境変数で明示的に指定しないと、古いバージョンでビルドされる
• baseURL を hugo.toml で正しく設定する必要がある
• サブモジュール（テーマ）は自動で取得されるが、初回は手動で git submodule update --init が必要

デプロイ後の運用

自動デプロイの快適さ

main ブランチにプッシュすると自動ビルドが走ります。

ビルド結果はCloudflareのダッシュボードで確認できますし、エラーがあればメール通知も来ます。

プレビューデプロイ

Pull Requestを作成すると、自動でプレビュー環境が生成されます。

本番環境に影響なくテストできるので便利ですね。

Cloudflare Pagesのおかげで、インフラ管理に時間を取られることなく、記事執筆に集中できています。

まとめ

Hugo + ClaudeCode + Cloudflare Pagesの組み合わせで、想像以上にスムーズに技術ブログを立ち上げられました。

良かった点

• Hugoの高速ビルドで執筆体験が快適
• ClaudeCodeのサポートで技術的な壁を素早く突破
• Cloudflareの自動デプロイで運用が楽

苦労した点

• テーマのオーバーライド構造の理解に時間がかかった
• CSSの細かい調整が必要だった

これから組み込み技術に関する記事を書き溜めていきます。

技術ブログを始めたい方の参考になれば幸いです。

参考リンク

• Hugo公式ドキュメント
• Hugo Theme Stack
• Cloudflare Pages
• ClaudeCode