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

フレームワーク Docusaurus Documentation Static Site
読了 3分

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

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

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

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

GitHubに上げる #

ビルドの成果物と依存関係はリポジトリに入れないよう、.gitignoreから押さえます。create-docusaurusが基本の.gitignoreを作ってくれますが、肝心なのは次の三つです。

.gitignore 
/build/
/node_modules/
/.docusaurus/

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

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

Cloudflare Pagesに接続 #

CloudflareのダッシュボードでWorkers & Pages → Create → Pages → Connect to Gitからリポジトリを選択します。DocusaurusはNodeプロジェクトなので、ビルド設定がシンプルです。

項目値
フレームワークプリセットDocusaurus
ビルドコマンドnpm run build
ビルド出力ディレクトリbuild
環境変数NODE_VERSION = 20

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

もっと簡単な道 — deployコマンド #

GitHub Pagesを使うなら、Docusaurusがデプロイコマンドを提供します。まずdocusaurus.config.jsにurl、baseUrl、organizationName、projectNameを埋めた後、実行します。

GitHub Pagesへ一度に 
npm run deploy

自分のコンピューターでビルドしてgh-pagesブランチに上げる方式です。チームで一緒に使うなら、プッシュ時に自動ビルドされるCloudflare側のほうが事故が少ないです。

カスタムドメイン接続 #

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

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

接続が終わると、HTTPS証明書はCloudflareが自動的に発行して更新します。カスタムドメインを使うときは、docusaurus.config.jsのurlとbaseUrlもそのドメインに合わせておきます。

まとめ #

今回の記事では、ドキュメントをGitHubに上げ、Cloudflare Pagesに接続してNodeのビルドを設定し、カスタムドメインまで付けました。これでドキュメントは本当のアドレスを持ってインターネット上に浮かんでいます。

次回は多言語とバージョン管理を扱います。Docusaurusが最も強い領域で、どちらも標準機能として備わっています。

X