docs サイトのローカル確認とデプロイの仕組み | BizLinkPartners 社内ドキュメント

エレベーターピッチ

これは何？　　: ドキュメントサイトを手元で確認する方法と、公開までの流れの手引きです。

だれのため？　: ドキュメントを書いて、見た目を確かめたい人のため。

なにが起きる？: コマンドを 1 つ実行 → サイトが手元に立ち上がる → 見たいページが自動で開く。

譲れない一線　: 公開への反映に手作業はありません。変更を送れば下書き版が、取り込まれれば本番が、勝手に更新されます。

だから　　　　: 「どうやって公開するんだっけ？」を覚えなくていい。書くことに集中できます。

一発コマンド（推奨）

bash scripts/docs-preview.sh                # ビルド → 配信 → トップを開く
bash scripts/docs-preview.sh <パス or URL>  # 指定ページを開く

引数は本番 URL をそのまま貼って OK（https://docs.bizlp.dev/...）。.html 付き・パスだけでも受け付ける。
配信には serve を使うため、URL に .html を付ける必要はない（本番と同じ感覚）。
フルビルドのため起動に約 5 分かかる（2026-06-04 実測: 611 ページ / 286 秒）。差分ビルドは ADR 起案中（KV draft docs-incremental-build）。

環境は 3 つ（ローカル / Preview / 本番）

環境	いつ作られる	URL	`.html`
ローカル	自分でコマンド実行	`http://localhost:3000/...`（docs-preview.sh / docs:serve）	不要
ローカル (watch)	`pnpm run docs:dev`	`http://127.0.0.1:8080/...`（live-server）	必須
Preview	ブランチを push するたび自動	PR の Checks →「Cloudflare Pages」のリンク先	不要
本番	main にマージされると自動	`https://docs.bizlp.dev`	不要

デプロイコマンドは存在しない。 ビルド設定はリポジトリ内ではなく Cloudflare Pages の Git 連携（ダッシュボード側）にあり、push / マージをトリガに全自動でビルド・公開される。

コマンド使い分け

コマンド	やること	向いている場面
`bash scripts/docs-preview.sh`	ビルド + 配信 + ブラウザ自動オープン	迷ったらこれ
`pnpm run docs:serve`	ビルド + 配信（port 3000）	上と同等（URL は手で開く）
`pnpm run docs:dev`	ビルド + 保存監視で自動再ビルド + 配信（port 8080）	書きながら確認。ただし現状は保存ごとにフルビルド（約 5 分）が走る点と `.html` 必須に注意
`pnpm run docs:build`	`_site/` に HTML 生成のみ（配信なし）	ビルドが通るかの確認・CI 相当

ハマりどころ

.html の非対称: live-server（docs:dev）だけ拡張子なし URL を解決できない（docs-build.mjs の LOCAL=1 が付与する .html リンクはこのため）。本番 URL をコピーして来たら .html を足す——か、最初から docs-preview.sh / docs:serve を使う。
nav 未登録の .md はどの環境でもビルドされない（404）。docs/_config.json への登録を忘れない（docs-nav-lint が CI で検出）。
大きな構成変更は merge 前に Preview で目視する（failure_patterns.md #40: build 成功 ≠ リンク・anchor 解決）。
ファイルの削除・リネーム後は古い HTML が _site/ に残るため、rm -rf _site してからビルドし直すと確実。

エレベーターピッチ

一発コマンド（推奨）

環境は 3 つ（ローカル / Preview / 本番）

コマンド使い分け

ハマりどころ

関連