這篇是給「想把文件站工程化、又不想完全公開」的人：
用 MkDocs（Markdown） 寫文件、用 GitHub 管版控，交給 Cloudflare Pages 自動 build/deploy，最後用 Cloudflare Zero Trust（Access） 的 Email policies（One-time PIN / Email OTP） 來做存取控管。

架構總覽

GitHub Repo（MkDocs 專案） → Cloudflare Pages（自動 build/deploy） → Zero Trust Access（驗證 / 授權） → 使用者瀏覽

為什麼選 MkDocs：.md 的低摩擦優勢

• 文件就是 .md：好寫、好改、好 diff、好 review
• mkdocs.yml 集中管理導覽：結構清楚、PR 可審
• 本機 mkdocs serve 即時預覽；上線交給 Pages 自動化

先補：Python venv（避免全域 pip 汙染）

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

pip install mkdocs mkdocs-material
mkdocs --version

mkdocs serve

離開 venv：

deactivate

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install -U pip
pip install mkdocs mkdocs-material
mkdocs --version

mkdocs serve

若 PowerShell 無法啟用 venv，可用：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
改完重開 PowerShell 再試。

Part A — Cloudflare Pages：從 GitHub 匯入 repo、自動部署 MkDocs

A1) 進到 Workers & Pages

A2) 建立 Pages 專案（Create application）

A3) 進入 Pages 的 Get started

這頁會同時出現 Workers / template 的入口；要做 Pages 的話，走底部 Looking to deploy Pages? → Get started。

A4) 選擇用 Git repo 匯入（Import an existing Git repository）

A5) 選 repo，Begin setup

A6) 設定 Build 指令與輸出目錄，Save and Deploy

典型 MkDocs 設定：

• Build command：pip install -r requirements.txt && mkdocs build
• Build output directory：/site

實務建議：把 MkDocs/主題/外掛固定在 requirements.txt若 repo 根目錄不是 MkDocs 專案，可用 Root directory（advanced）指定子目錄

Part B — Zero Trust Access：用 Email policies 讓文件站「需要驗證才能看」

目標很單純：沒通過 Access policy 就看不到內容。
最常見且最好排錯的策略是：Allow（上面） + deny-all。

B1) 進到 Zero Trust → Access controls → Applications

B2) Add an application：選 Self-hosted

Pages/靜態站通常用 Self-hosted 來保護站點。

B3) Configure application：設定 Public hostname 與 Session Duration

• Session Duration：24 hours
• Domain：填 *.pages.dev 或 custom domain
• Path：留空＝保護整站；指定 path＝保護部分路徑

B4) Policies：建立「允許」規則（Email domain）與「拒絕全部」

先建立 Allow policy（Emails ending in）

如果你還沒加任何 policies，會看到空清單；按 Create new policy。

在 Add policy 裡：

• Action：Allow
• Selector：Emails ending in
• Value：填你要允許的網域（例如 @gmail.com 或你的公司網域）

再建立 deny-all（Block）

最後一條放 Deny-all / Block，確保「不符合 allow 的一律擋」。

完成後，清單大概長這樣（Allow 在上、Deny-all 在下）：

觀念：Access 會依序評估 policy（top-to-bottom）。
你想要的效果通常是「符合 allow → 放行；不符合 → 落到 deny-all 被擋」。

B5) Policy tester：快速驗證規則有沒有命中

Policy tester 會用「最近看到的 identity」去測試，適合用來快速確認你配置的 selector 是否正確。

常見解讀：若你用 @gmail.com allow，但實際使用者是公司網域，tester 顯示 BLOCKED 是合理的。反過來，如果你以為應該放行但顯示 BLOCKED，通常是 selector/值填錯、或 rule order 放錯。

B6) 實際登入畫面（Email OTP / One-time PIN）

設定完成後，使用者訪問站點時會先被導到 Cloudflare Access 的登入頁。
Email OTP 模式就是輸入 email，按 Send me a code。

Email OTP 收不到信怎麼辦（運維視角）

這類問題多數不在 Pages，而是在「郵件投遞」鏈路（企業信箱、反垃圾、延遲、封鎖）。

最短排查路徑：

1. Zero Trust → Access → Logs：看是否真的有觸發 OTP、是否送出成功、是否被 policy 擋
2. 用 Gmail/Outlook 測試：快速排除企業信箱策略造成的擋信
3. 你無法控 mail server：直接改 Google / GitHub OAuth 作為 Login method（通常更穩）

結語：

文件要「能改、能追、能控」：GitHub 管內容、MkDocs 用 .md 寫、Pages 自動部署、Zero Trust 先驗證再看。
下一步就是把 Allow policy 擴到你的團隊網域，並保留 deny-all 當最後防線；OTP 不穩就直接換 OAuth，省下大量排錯時間。