↓メインコンテンツへスキップ

Hugo + Congo + Cloudflare Workers でブログを作り直しました

久しぶりにブログの構成を見直しました。owner203 です。

これまでは WordPress を使っていましたが、今後は記事を Markdown で管理することにしました。Hugo と Congo でサイトを生成し、Cloudflare Workers Static Assets で配信します。まずは新しいブログの土台ができたので、構成と考えたことを残しておきます。旧記事の移行はこれからです。

Hugo で静的なサイトを作る #

Hugo は、Markdown とテンプレート、設定ファイルから HTML などを生成する静的サイトジェネレーターです。

flowchart TD Markdown --> Hugo Theme["Theme (Congo)"] --> Hugo Configuration --> Hugo Hugo --> Files["public/"] Files --> Hosting["Workers Static Assets"]

記事の変換はビルド時に済ませます。公開先に置くのは生成されたファイルなので、配信のために Hugo や Go を動かし続ける必要はありません。このブログのための PHP やデータベースも不要になります。

このブログでは技術メモや考えたことを書ければ十分なので、この形にしました。記事をテキストファイルとして持ち、変更履歴も Git で追えるようにしました。

テーマとサイトの中身を分ける #

テーマには Congo を選びました。文章とコードを中心にした表示ができ、検索や外観の切り替えもテーマの設定で使えます。サイトの見た目は、なるべく標準のままにしています。

テーマのファイルは直接変更せず、サイト側の設定や画像を分けて管理します。

テーマは見せ方を担当し、記事や画像はブログ側に置きます。現在の構成は、おおむね次のようになっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
.
├── content/
│   ├── posts/          # Articles and their resources
│   └── pages/          # About and links
├── assets/
│   ├── css/custom.css
│   └── img/            # Avatar and logo
├── static/             # Favicons and other public files
├── hugo.toml
├── go.mod
├── go.sum
└── wrangler.jsonc

設定は hugo.toml、追加の CSS は assets/ に置いています。テーマのテンプレートやダウンロードされたキャッシュには手を入れていません。

記事ごとの画像は、ページバンドルとして Markdown と同じディレクトリに置きます。

1
2
3
content/posts/my-post/
├── index.md
└── image.png
1
![Description](image.png)

assets/ は Hugo で処理を加える画像や CSS、static/ はそのまま公開先へコピーするファイルに使っています。記事固有の画像まで static/ に集めず、記事と一緒に移動できる状態にしておきます。

テーマを更新するときに自分の変更と混ざりにくくなり、将来テーマを替える場合も Markdown と画像は残せます。テーマ固有の shortcode や設定だけは、別途見直しが必要です。

Congo は Hugo Modules で管理する #

このブログでは Git submodule を使わず、Hugo Modules でテーマを管理しています。Go Modules の仕組みを利用するので、ビルド環境には Go も入れています。

hugo.toml で読み込むモジュールを指定します。

1
2
[[module.imports]]
path = "github.com/jpanther/congo/v2"

初回はプロジェクトのモジュールを初期化し、使用するテーマのバージョンを指定します。以下は今回導入したバージョンで、example.com/my-blog はモジュール名の例です。

1
2
3
mise exec -- hugo mod init example.com/my-blog
mise exec -- hugo mod get github.com/jpanther/congo/v2@v2.14.0
mise exec -- hugo mod tidy

バージョンは go.mod、チェックサムは go.sum に記録されます。この二つを Git で管理し、テーマ本体はビルド時に取得してキャッシュします。サイトのソースに themes/ を置いたり、テーマのソースをコピーしたりする必要はありません。

更新時もバージョンを指定し、差分と表示を確認してから取り込みます。モジュールの整理は hugo mod tidy で行います。

ローカル環境とプレビュー #

Node.js、Go、Hugo Extended は mise で管理しています。この記事を書いた時点の .mise.toml は次のとおりです。

1
2
3
4
[tools]
node = "24"
go = "1.27.1"
hugo-extended = "0.166.0"

Go と Hugo はバージョンを固定し、Node.js はローカルと CI の両方で 24 系を使います。Wrangler などの npm 依存は package.json と package-lock.json で管理しています。

手元では、ビルドとプレビューを自作スクリプトにまとめ、次のように実行しています。npm run ... は、package.json に登録したこのブログ専用のコマンドです。

1
2
3
4
mise trust
mise install
mise exec -- npm ci
mise exec -- npm run preview

これで 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 の静的ファイルに関する設定は、次の部分です。

1
2
3
4
5
6
7
{
  "assets": {
    "directory": "./public",
    "html_handling": "force-trailing-slash",
    "not_found_handling": "404-page"
  }
}

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(自動実行)

flowchart TD PR["Pull request
opened / updated"] --> Check["Build and validate
(automatic)"] Main["Push / merge
to main"] --> Check

Deploy(開始だけ手動、以降は自動実行)

main の CI が成功したこととプレビューを確認してから、Deploy を手動で開始します。開始後は npm run check による再検証、最新コミットの確認、公開用ビルド、アップロードまで自動で進みます。

flowchart TD Start["Run Deploy on main
(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 として登録しています。

1
2
CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_API_TOKEN

今回のデプロイで確認した API Token の権限は次の二つです。

ScopePermission
Deployment accountWorkers Scripts Write
Custom Domain zoneWorkers Routes Write

用意した deploy.yml は、CLI からも次のコマンドで開始できます。

1
gh workflow run deploy.yml --ref main

開始後の処理は自動化しているので、毎回コマンドを順番に実行する手間はありません。

これからの記事更新 #

新しい記事は下書きから始めます。

1
mise exec -- hugo new content posts/my-post/index.md

公開前に draft = false に変更し、公開対象だけをプレビューします。この操作と構成のチェックも、専用の npm scripts にまとめました。

1
2
3
mise exec -- npm run preview:production
# Stop the preview with Ctrl+C before running checks.
mise exec -- npm run check

公開用ビルドでは public/ を作り直し、下書きや未来の日付の記事を除外します。

旧 WordPress の記事は、公開状態と画像を確認しながら、少しずつ Markdown に移していく予定です。