Hugo + Congo + Cloudflare Workers でブログを作り直しました
目次
久しぶりにブログの構成を見直しました。owner203 です。
これまでは WordPress を使っていましたが、今後は記事を Markdown で管理することにしました。Hugo と Congo でサイトを生成し、Cloudflare Workers Static Assets で配信します。まずは新しいブログの土台ができたので、構成と考えたことを残しておきます。旧記事の移行はこれからです。
Hugo で静的なサイトを作る #
Hugo は、Markdown とテンプレート、設定ファイルから HTML などを生成する静的サイトジェネレーターです。
記事の変換はビルド時に済ませます。公開先に置くのは生成されたファイルなので、配信のために Hugo や Go を動かし続ける必要はありません。このブログのための PHP やデータベースも不要になります。
このブログでは技術メモや考えたことを書ければ十分なので、この形にしました。記事をテキストファイルとして持ち、変更履歴も Git で追えるようにしました。
テーマとサイトの中身を分ける #
テーマには Congo を選びました。文章とコードを中心にした表示ができ、検索や外観の切り替えもテーマの設定で使えます。サイトの見た目は、なるべく標準のままにしています。
テーマのファイルは直接変更せず、サイト側の設定や画像を分けて管理します。
テーマは見せ方を担当し、記事や画像はブログ側に置きます。現在の構成は、おおむね次のようになっています。
| |
設定は hugo.toml、追加の CSS は assets/ に置いています。テーマのテンプレートやダウンロードされたキャッシュには手を入れていません。
記事ごとの画像は、ページバンドルとして Markdown と同じディレクトリに置きます。
| |
| |
assets/ は Hugo で処理を加える画像や CSS、static/ はそのまま公開先へコピーするファイルに使っています。記事固有の画像まで static/ に集めず、記事と一緒に移動できる状態にしておきます。
テーマを更新するときに自分の変更と混ざりにくくなり、将来テーマを替える場合も Markdown と画像は残せます。テーマ固有の shortcode や設定だけは、別途見直しが必要です。
Congo は Hugo Modules で管理する #
このブログでは Git submodule を使わず、Hugo Modules でテーマを管理しています。Go Modules の仕組みを利用するので、ビルド環境には Go も入れています。
hugo.toml で読み込むモジュールを指定します。
| |
初回はプロジェクトのモジュールを初期化し、使用するテーマのバージョンを指定します。以下は今回導入したバージョンで、example.com/my-blog はモジュール名の例です。
| |
バージョンは go.mod、チェックサムは go.sum に記録されます。この二つを Git で管理し、テーマ本体はビルド時に取得してキャッシュします。サイトのソースに themes/ を置いたり、テーマのソースをコピーしたりする必要はありません。
更新時もバージョンを指定し、差分と表示を確認してから取り込みます。モジュールの整理は hugo mod tidy で行います。
ローカル環境とプレビュー #
Node.js、Go、Hugo Extended は mise で管理しています。この記事を書いた時点の .mise.toml は次のとおりです。
| |
Go と Hugo はバージョンを固定し、Node.js はローカルと CI の両方で 24 系を使います。Wrangler などの npm 依存は package.json と package-lock.json で管理しています。
手元では、ビルドとプレビューを自作スクリプトにまとめ、次のように実行しています。npm run ... は、package.json に登録したこのブログ専用のコマンドです。
| |
これで http://127.0.0.1:8787/ に下書きを含めたサイトを表示します。スクリプトでは下書きプレビューの出力先を .preview/ に指定し、公開用ビルドには Hugo の標準の public/ を使っています。
執筆中は npm run dev で Hugo のライブリロードを使い、公開前には Wrangler でも確認します。Wrangler のプレビューはビルド時点の内容なので、記事を編集したら起動し直します。
Workers Static Assets で配信する #
公開先には Cloudflare Workers Static Assets を使っています。Hugo が生成した public/ を指定すればよく、今回は Worker のスクリプトも書いていません。
wrangler.jsonc の静的ファイルに関する設定は、次の部分です。
| |
Hugo は記事を posts/<slug>/index.html の形で出力します。URL も /posts/<slug>/ に揃えるため、force-trailing-slash を指定しています。
存在しない URL には、404-page で Hugo が生成した 404 ページを返します。見た目だけのエラーページではなく、HTTP ステータスも 404 になります。
公開 URL は hugo.toml の baseURL に、Custom Domain は wrangler.jsonc の routes に設定します。baseURL は canonical URL や RSS、サイトマップにも使われるので、実際の公開先と揃えておきます。
検証は自動、公開は手動 #
Cloudflare 側の Workers Builds による Git 連携は使っていません。CI/CD はほかのリポジトリと同じく GitHub Actions にまとめ、Cloudflare 側のビルド枠は使わない構成にしました。
もう一つの理由は、公開するタイミングを自分で決めたいからです。README だけの変更や依存関係の更新が入るたびに、そのままサイトを公開する必要はありません。プレビューを確認し、公開してよいと判断したところでデプロイします。
ワークフローは ci.yml と deploy.yml に分けています。CI は PR の作成・更新時と、マージを含む main への push 時に自動で実行されます。
CI(自動実行)
opened / updated"] --> Check["Build and validate
(automatic)"] Main["Push / merge
to main"] --> Check
Deploy(開始だけ手動、以降は自動実行)
main の CI が成功したこととプレビューを確認してから、Deploy を手動で開始します。開始後は npm run check による再検証、最新コミットの確認、公開用ビルド、アップロードまで自動で進みます。
(manual)"] -->|Automatic from here| Validate["Validate again"] Validate --> Current{"Still the main tip?"} Current -- Yes --> Build["Production build"] Build --> Upload["wrangler deploy"] Current -- No --> Stop["Stop"]
GitHub の production Environment に、次の二つを Secrets として登録しています。
| |
今回のデプロイで確認した API Token の権限は次の二つです。
| Scope | Permission |
|---|---|
| Deployment account | Workers Scripts Write |
| Custom Domain zone | Workers Routes Write |
用意した deploy.yml は、CLI からも次のコマンドで開始できます。
| |
開始後の処理は自動化しているので、毎回コマンドを順番に実行する手間はありません。
これからの記事更新 #
新しい記事は下書きから始めます。
| |
公開前に draft = false に変更し、公開対象だけをプレビューします。この操作と構成のチェックも、専用の npm scripts にまとめました。
| |
公開用ビルドでは public/ を作り直し、下書きや未来の日付の記事を除外します。
旧 WordPress の記事は、公開状態と画像を確認しながら、少しずつ Markdown に移していく予定です。