MkDocsでマニュアルを作る #4 Cloudflare Pagesでデプロイしてドメインをつなぐ

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

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

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

この記事では、依存関係を固定してGitHubに上げ、Cloudflare Pagesにつないでビルドを設定し、カスタムドメインを付けるところまで扱います。

依存関係を固定する — requirements.txt #

ビルドサーバーが自分のPCと同じバージョンでドキュメントを作るようにするには、使うパッケージを書いておく必要があります。これがrequirements.txtです。

mkdocs-material

バージョンをより厳密に固定するなら、mkdocs-material==9.5.0のように書きます。このファイルがあってこそ、ビルドサーバーが同じツールをインストールして同じ結果を出します。

GitHubに上げる #

ビルド成果物はリポジトリに入れないように、.gitignoreから作ります。MkDocsのビルド成果物はsiteフォルダです。

site/

その後、リポジトリを初期化してプッシュします。

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

Cloudflare Pagesにつなぐ #

CloudflareのダッシュボードでWorkers & Pages → Create → Pages → Connect to Gitからリポジトリを選びます。MkDocsはPythonなので、ビルドコマンドで先に依存関係をインストールする必要があります。

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

もっと簡単な道 — gh-deploy #

GitHub Pagesを使うなら、MkDocsがデプロイまで1コマンドでやってくれます。ビルドした結果をgh-pagesブランチに上げる方式です。

mkdocs gh-deploy

手間がもっとも少ないですが、ビルドを自分のPCで直接回して上げるという点がCloudflare連携とは違います。チームで一緒に使うなら、プッシュ時に自動ビルドされるCloudflare側のほうがトラブルが少ないです。

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

pages.devのアドレスの代わりに、自分で買ったドメインを付けます。PagesプロジェクトのCustom domains → Set up a domainでドメインを入力します。別のところでDNSを管理しているなら、次のレコードを直接入れます。

タイプ    名前     値
CNAME    docs     プロジェクト名.pages.dev

接続が終わると、HTTPS証明書はCloudflareが自動で発行・更新します。

まとめ #

この記事では、requirements.txtで依存関係を固定してGitHubに上げ、Cloudflare Pagesにつないでビルドを設定し、カスタムドメインまで付けました。これでドキュメントは本物のアドレスを持ってインターネット上に浮かんでいます。

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