こんにちは、たひです。

普段は 組み込み電気設計エンジニア として、回路図とファームウェアと格闘している人間です。Web/フロントエンドの実務経験はほぼゼロ。HTML/CSSも「かつて触ったことがある」程度で、Goテンプレートに至っては初見でした。

そんな自分が、技術メモを残す場として Hugo + ClaudeCode で技術ブログを立ち上げました。 ClaudeCode に手取り足取り聞きながら進めた結果、初日のうちに公開までこぎつけられたので、その過程を残しておきます。

組み込みエンジニアから見たHugoの居心地のよさ

ブログ環境の候補は WordPress、Next.js、Hugo などいくつか挙がりました。最終的に Hugo に決めたのは、普段の組み込み開発の感覚と地続きだったから です。

1. ビルド成果物が静的ファイル群で完結する

Hugo は Markdown を読み込んで public/ に静的HTMLを吐き出すだけのツールです。 ファームウェアでいう「ビルド成果物の .bin を生成する」感覚に近くて、ランタイムに何が起きているか分からない という不安がない。 DBもサーバーサイドのロジックもないので、デプロイ後の挙動は事前ビルドの時点で完全に確認できます。

2. テキストベースで Git 管理できる

記事はすべて Markdown。普段 C/C++ のソースを Git で管理しているのと同じ感覚で git diff で内容を追えるし、ブランチで下書きを寝かせたり、コミットメッセージで履歴を残したりもできる。 WYSIWYG の管理画面にログインして編集する WordPress 的なワークフローより、組み込みエンジニアには圧倒的に馴染みやすいです。

3. ビルドが爆速

Go 製なので、数百ページでも数秒で終わります。 ファームウェア開発の「Build & Flash で30秒〜1分待つ」みたいな間延びがなく、Markdown を保存した瞬間にプレビューが更新される。執筆体験としてかなり快適です。

4. 依存関係が浅い

Hugo Extended は単一バイナリ。npm の依存ツリーが膨らんでいく心配がない。 （後述のとおり最終的には Docker に寄せましたが、それでも Dockerfile で Hugo Extended を1行で取得するだけで済んでいます。）

ClaudeCodeなしでは詰んでいた箇所

「組み込み出身でも Hugo は触れる」とは書きましたが、実際の構築過程で詰まった部分は ほぼ全部 ClaudeCode に助けてもらっています。

組み込みエンジニアにとって、Hugo のテンプレート構文（Goテンプレート言語）も、SCSS も、Cloudflare Pages の挙動も、全部「初見の方言」です。 ClaudeCode を翻訳機として挟むと、これがいきなり地続きの作業になりました。

ディレクトリ構造とテンプレート階層を即座に把握できた

「layouts/ と themes/<theme>/layouts/ の上書き優先順位（Lookup Order）はどうなってるの？」みたいな疑問に、ドキュメント該当箇所込みで答えてくれます。 自分で Hugo の Lookup Order を読み解いていたら、確実に半日は溶かしていました。

エラーメッセージの解読が速い

Hugo の error: failed to render ... 系のエラーは、テンプレート式の文脈に依存していて、初心者には原因が見えません。 ClaudeCode に貼ると「これは .Site.Params.xxx の参照型が違う」のように切り分けてくれて、修正差分まで提示してくれます。 組み込みでいう「LA 当てなくても症状からバグの当たりが付く先輩」が常駐している感覚です。

やりたい見た目をテンプレート差分の形で出してくれる

「記事カードに公開日と更新日の両方を出したい」と頼むと、layouts/partials/article/components/details.html をテーマからコピーして上書きする差分を出してくれます。 テーマ全体をフォークせず、必要なファイルだけパッチする という運用が成立するのが大きい。組み込みでいう「他人のミドルウェアに割込ハンドラだけ差し替える」感覚です。

Hugo の知識ゼロでも hugo.toml を整えられる

hugo.toml の各パラメータが何を意味するのか、SEO の OpenGraph 設定はどう書くか、サイトマップやページネーションの設定値は何が妥当か、こういう「経験値で決める」ところを ClaudeCode が下書きしてくれました。 あとは自分の好みに合わせて値を調整するだけで済んだので、ドキュメントを最初から読む必要がほぼなかったです。

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の助けで、テーマの構造を理解しながらカスタマイズを進められました。

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

開発環境はDockerに統一

最初はWindowsに直接Hugo Extendedを入れて運用していたんですが、後から WSL2 + Docker Desktop ベースに切り替えました。

• Hugo Extended・Node.js・Playwright をまとめた1つのイメージにする
• ローカルにHugoバイナリを置かない方針（バージョンずれや「自分の環境では動く」を防ぐ）
• docker compose up -d で開発サーバー起動、docker compose down で停止

1
2
3
4
5
6

# 開発サーバー（http://localhost:1313、下書き含む）
docker compose up -d

# 単発コマンド（記事生成・本番ビルド等）
docker compose run --rm dev hugo new content/post/YYYY/MM/<slug>/index.md
docker compose run --rm dev hugo --minify

レイアウト変更時のスクリーンショット検証も Playwright をコンテナ内で動かしているので、Cloudflare Pages 側のビルド環境と同じ Linux ベースで挙動確認できるのが安心です。

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（Cloudflare 側で Hugo Extended が必要な場合は HUGO_VERSION_EXTENDED も同値で指定）

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

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

• Cloudflare Registrarで tahi314.work を取得
• DNS設定は自動で完了
• HTTPS証明書も自動発行

めちゃくちゃ楽でした。

注意したポイント

• Hugoのバージョンを環境変数で明示的に指定しないと、古いバージョンでビルドされる
• baseURL を hugo.toml で正しく設定する必要がある
• サブモジュール（テーマ）は自動で取得されるが、初回は手動で git submodule update --init が必要
• 増分ビルドで public/scss/style.min.<hash>.css が蓄積する問題には hugo.toml に cleanDestinationDir = true を入れて回避（毎ビルドで public/ を掃除してくれる）

デプロイ後の運用

自動デプロイの快適さ

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

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

プレビューデプロイ

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

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

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

まとめ

Hugo + ClaudeCode + Cloudflare Pages の組み合わせは、「Web/フロントエンドが本職じゃないエンジニアでも、自分の道具として運用できるブログ環境」だと感じました。

組み込みエンジニア視点での感想

• Hugo は「静的ファイルを吐くだけのビルドツール」なので、ファームウェア感覚で挙動を予測できる
• ClaudeCode が Goテンプレート / SCSS / Cloudflare の “方言” を翻訳してくれるので、初見でも詰まらない
• Cloudflare Pages の自動デプロイで、インフラ管理ではなく記事執筆に時間を使える

苦労した点

• テーマのオーバーライド構造（Lookup Order）の理解に時間がかかった
• 細かいCSSの差分調整は結局自分で試行錯誤が必要

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

「組み込み出身だけど技術ブログを持ちたい」という人の参考になれば幸いです。

参考リンク

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