靜態網站建置¶

概述¶

ekkorn-doc 使用 MkDocs Material 將聚合後的文件編譯為靜態網站，目前透過 Docker 提供本地預覽，Stage 2 將部署至 Cloudflare Pages。

MkDocs 設定¶

設定檔位於 site/mkdocs.yml，主要配置：

設定	值	說明
`docs_dir`	`docs`	相對於 mkdocs.yml 的文件來源目錄
`site_dir`	`../public`	編譯輸出目錄
`theme`	Material	支援暗色模式切換、搜尋高亮、程式碼複製
`plugins.search.lang`	`zh`	中文搜尋支援

已啟用的 Markdown 擴充¶

admonition — 提示框（note, warning, tip 等）
pymdownx.superfences — 程式碼區塊 + Mermaid 圖表
pymdownx.tabbed — 分頁式內容
tables — 表格
toc — 目錄與 permalink

導覽 (nav)¶

目前 nav 為手動維護，僅包含首頁與全域規範。各 repo 的文件在 sync-docs.sh 同步後可手動加入，未來規劃改用 mkdocs-awesome-pages-plugin 自動生成。

本地預覽¶

# 先同步各 repo 的 docs（需要 yq）
bash scripts/sync-docs.sh

# 啟動 MkDocs dev server（http://localhost:8000）
docker compose up docs

Docker 掛載 ./site 為唯讀 volume，修改 Markdown 檔案後自動 hot reload。

Dockerfile¶

基於 python:3.12-slim，安裝 mkdocs-material 和 yq，expose port 8000。

Cloudflare Pages 部署（Stage 2）¶

已在 workflow 中預留設定（目前註解），啟用時需要：

在 GitHub Secrets 設定 CF_API_TOKEN 和 CF_ACCOUNT_ID
取消 .github/workflows/sync-and-build.yml 中 Cloudflare 部署步驟的註解
在 Cloudflare 建立 ekkorn-docs Pages 專案

站點結構¶

site/docs/                    # sync-docs.sh 填充
├── index.md                  # 首頁（手動維護）
├── workspace/                # 全域規範（來自 workspace/docs/，排除 workspace-sync.md）
│   ├── repo_overview.md
│   └── rules/safety.md
├── ekkorn-doc/               # ekkorn-doc 自身的 docs/（CI 自動同步）
│   ├── overview.md
│   ├── architecture.md
│   ├── modules/
│   └── contracts/
├── app-server/               # 各 repo 的 docs/（CI 自動同步）
│   ├── overview.md
│   └── ...
├── want-payment/
└── ...