Hugoでマニュアルを作る #4 Cloudflare Pages でデプロイしてドメインを接続する

フレームワーク Hugo Documentation Static Site
読了 4分

#3 まで来ると、ローカルで見やすいドキュメントが整います。しかし localhost は自分だけしか見られません。この記事では、このドキュメントを誰でもアドレスでアクセスできるように送り出します。

今回のシリーズは Hugoでマニュアルを作る の全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 サイドバーと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、コールアウト
  • #4 Cloudflare Pages でデプロイしてドメインを接続する ← この記事
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索インデックス、アクセシビリティ、ドキュメント文化

この記事では GitHub に上げ、Cloudflare Pages に接続してビルドを整え、カスタムドメインを付ける ところまで扱います。

静的サイトはどこに上げるのか #

Hugo が作った成果物は、HTML・CSS・JS の静的ファイルの束です。サーバーで動くコードがないので、ファイルをそのまま受け取ってくれるホスティングで十分です。この記事では Cloudflare Pages を使います。無料枠がたっぷりあり、Git リポジトリにプッシュすると自動でビルドしてデプロイし、世界中の CDN と HTTPS が標準で付いてきます。

1. GitHub に上げる #

Cloudflare Pages は Git リポジトリを見てビルドします。まずドキュメントを GitHub に上げます。ビルド成果物とキャッシュはリポジトリに入れないよう、.gitignore から作ります。

.gitignore 
/public/
/resources/_gen/
.hugo_build.lock

続いてリポジトリを初期化してプッシュします。

GitHub に上げる 
git init
git add .
git commit -m "docs: 最初のドキュメント"
git branch -M main
git remote add origin https://github.com/自分のアカウント/my-docs.git
git push -u origin main

2. Cloudflare Pages に接続 #

Cloudflare ダッシュボードで Workers & Pages → Create → Pages → Connect to Git から、今上げたリポジトリを選びます。続いてビルド設定を次のように指定します。

項目値
フレームワークプリセットHugo
ビルドコマンドhugo --gc --minify
ビルド出力ディレクトリpublic

Save and Deploy を押すと最初のデプロイが始まり、終わると プロジェクト名.pages.dev のアドレスができます。以後は main にプッシュするたびに自動で再ビルドされます。

3. ビルド環境 — Hugo のバージョンと Go #

デプロイが一度で通らない場合、十中八九ビルド環境の問題です。二つを確認します。

一つ目は Hugo のバージョンです。環境変数に HUGO_VERSION を指定して、ローカルと同じバージョンに合わせます。Hextra のように内蔵のアセット処理を使うテーマは Extended バージョンが必要ですが、Cloudflare は HUGO_VERSION で指定したバージョンの Extended ビルドをインストールします。

環境変数値(例)
HUGO_VERSION0.140.0

二つ目は Go です。#1 で見たとおり Hextra は Hugo Modules で配布され、モジュールをダウンロードするには Go が必要です。Cloudflare のビルドイメージには Go が入っているので大抵そのまま通りますが、モジュールを取得できずビルドが止まる場合は、GO_VERSION 環境変数を追加してバージョンを明示すれば解決します。

4. カスタムドメインの接続 #

pages.dev のアドレスの代わりに、自分で買ったドメインを付けます。Pages プロジェクトの Custom domains → Set up a domain でドメインを入力します。

ドメインをすでに Cloudflare で管理中なら、DNS レコードが自動で追加されます。別の場所で管理しているなら、そちらの DNS に次のレコードを直接入れます。

DNS レコード (サブドメイン) 
種別    名前     値
CNAME   docs     プロジェクト名.pages.dev

ルートドメイン(example.com)に直接付けるには、CNAME フラット化に対応した Cloudflare DNS を使うのが最もすっきりします。接続が終わると、HTTPS 証明書は Cloudflare が自動で発行・更新します。

一つの落とし穴 — 公開日と予約 #

デプロイができたあと、一度はぶつかる問題があります。未来の日付で書いておいた記事が、その日になっても表示されないケースです。

Hugo は既定で未来の日付の記事をビルドから除外します。そして Cloudflare Pages は プッシュがあったときだけ 再ビルドします。この二つが合わさると、未来の日付で予約しておいた記事は、日付になっても自動では公開されません。その日に新しいビルドが走らないからです。予約公開がどうしても必要なら、毎日一度ビルドをトリガーする仕掛け(予約されたデプロイフック)を別途用意する必要があります。それが負担なら、記事を書くたびにその日の日付で公開するほうが単純で事故がありません。

まとめ #

この記事では、ドキュメントを GitHub に上げ、Cloudflare Pages に接続してビルドを整え、カスタムドメインまで付けました。これでドキュメントは本物のアドレスを持ってインターネット上に存在します。

次回では 多言語とバージョン管理 を扱います。一つのドキュメントを複数の言語で提供し、製品のバージョンが上がるときに古いドキュメントをどう一緒に維持するかを整理します。

X