2026-07-17 Cloudflare Pages 文件站部署 — SUMMARY

一次 arc 部署了兩個文件站（test repo docs-site 站 + BE specs 手冊站），並為 BE specs 加了版本導覽頁機制。本檔記 BE 側為主，test 側部署細節記在 test repo docs-site/README.md 部署段。

§1

為何做

docs-site（test repo）與 FR-047 spec 手冊（BE repo）原本都只有「file:// 離線看」或「rsync 到公司 server」的假設。Raymond 決定用 Cloudflare Pages（免費方案）做正式對外託管，且拍板 各 repo 文件站分開部署、各自網址（原本考慮過單一 guidantai-docs 站聚合多 repo，因 Pages 一專案只能連一 repo、跨 repo 聚合要 sync script 副本，放棄聚合改分站）。

§2

上線結果（皆已驗證 200）

站	網址	來源 repo / 輸出目錄	觸發
測試文件站	https://guidant-ai-test-docs.pages.dev	compliance-manager-test / `docs-site`	push main 且動到 `docs-site/*`
SPEC 手冊站	https://guidant-ai-spec-docs.pages.dev	compliance-manager-be / `docs/specs`	push main 且動到 `docs/specs/*`

兩站皆：GitLab 整合自動部署、無 build command（html 是版控內產物）、免費方案（頻寬/請求無限，500 builds/月）。

SPEC 站 URL 結構：/ 版本導覽頁 → /v1.8.0/html/README.html 各版手冊入口。

§3

BE commits（已 push origin/main）

hash	內容
`0049479b`	`render_html.py` 加 `build_version_index()`：掃 `docs/specs/v*/html/README.html` 產 `docs/specs/index.html` 版本卡片導覽頁（新版在前、最新標記）；整版 build 末尾自動再生 + `--index-only` 模式
`472e331f`	導覽頁維護備註（「本頁由 render_html.py 產生…」）從畫面移除改 HTML 註解——對外頁不露內部資訊

test repo commit（未 push）：aa849cf docs-site/README.md 部署段改記 Pages 實況。

§4

行為差異

python scripts/deliverables/render_html.py docs/specs/v1.8.0 現在末尾會自動重生 docs/specs/index.html；未來開 v1.9.0/ 重跑 build，導覽頁自動長出新卡，零手動。
spec 產線變成：改 md → 跑 render_html.py → commit（含 html/ + index.html）→ push main → 自動上線。
push to main 從「純備份」升格為「上線開關」——只要 commit 動到 docs/specs/（BE）或 docs-site/（test）就會部署。

§5

部署操作 handover（dashboard 側，Raymond 操作）

Cloudflare dashboard → Workers & Pages；兩專案皆 Raymond 個人帳號。
建站三要點：Framework 預設「無」、build command 留空、輸出目錄如上表。
組建監看路徑在專案建好後設：專案 → 設定 → 組建 → Build watch paths → include。
踩過的坑 ×2：輸出目錄欄位貼上時帶尾端空格 → Output directory "docs/specs " not found，兩個站都踩了一次。log 特徵是引號內路徑尾有空白；清空重打即解。
另一個入口坑：dashboard「建立應用程式」預設把人導去 Workers Git 流程（特徵：部署命令 npx wrangler deploy、要建 API Token）——要切到 Pages 分頁走 Connect to Git 才是本 arc 用的流程。

§6

未決 / follow-up

Cloudflare Access（限 email 登入）未設——兩站目前知道網址就能看。Raymond 已知悉，要加時再設（免費層 50 使用者內）。
test repo aa849cf 未 push（push 等 Raymond 明示；下次 push 會觸發一次 docs-site 部署，無害）。
BE docs/specs/v1.8.0/html/README.html 工作區曾有誤植字元 ㄥ（來源不明的手滑），已 revert——html 是產物勿手改的又一例證。