架構說明

目錄結構

ekkorn-doc/
├── workspace/                # 全域 AI 規範 Source of Truth
│   ├── CLAUDE.md             → 部署至 $EKKORN_WORK_DIR/CLAUDE.md
│   ├── GEMINI.md             → 部署至 ~/.gemini/GEMINI.md
│   ├── docs/                 → 部署至 $EKKORN_WORK_DIR/docs/
│   │   ├── repo_overview.md
│   │   ├── workspace-sync.md （內部流程，不同步至靜態網站）
│   │   └── rules/safety.md
│   └── .claude/commands/     → 部署至 $EKKORN_WORK_DIR/.claude/commands/
│       ├── plan.md, execute.md, review.md, commit.md, pr.md, ticket.md, doc.md
├── scripts/
│   ├── repos.yml             # 所有 repo 清單（single source of truth）
│   ├── sync-docs.sh          # CI 用：從各 repo sparse checkout docs/
│   ├── deploy-config.sh      # 本地用：部署 workspace/ 到工作目錄
│   └── git-fetch-all.sh      # 批次 fetch 所有本地 repo
├── site/                     # MkDocs 站點
│   ├── mkdocs.yml            # MkDocs Material 設定
│   └── docs/                 # 聚合後的文件（CI 自動填充，.gitignore 排除）
│       └── index.md          # 首頁（手動維護）
├── .github/workflows/
│   └── sync-and-build.yml    # CI：同步 + 建置
├── docs/                     # ekkorn-doc 專案自身的文件
├── Dockerfile                # MkDocs 本地預覽用
└── docker-compose.yml

技術選型

技術	用途	選型理由
MkDocs Material	靜態網站生成	Markdown 原生、搜尋/暗色模式/Mermaid 內建、Python 生態簡單
yq	YAML 解析	在 Bash 腳本中解析 repos.yml，無需引入程式語言 runtime
Git sparse checkout	文件拉取	只下載 docs/ 目錄，節省 CI 頻寬與時間
Docker	本地預覽	一鍵啟動，不需本地安裝 Python/MkDocs
Cloudflare Pages	靜態網站托管（Stage 2）	免費、CDN、自動 HTTPS
GitHub Actions	CI/CD	與 GitHub 原生整合，支援排程觸發

CI/CD Pipeline

觸發條件：
  - 每天 UTC 19:00（台灣凌晨 3 點）
  - push 到 main（workspace/、site/mkdocs.yml、scripts/repos.yml、workflow 自身）
  - 手動觸發（workflow_dispatch）

流程：
  1. Checkout ekkorn-doc
  2. 安裝 mkdocs-material + yq
  3. sync-docs.sh：遍歷 repos.yml，sparse checkout 各 repo 的 docs/ → site/docs/<name>/
  4. mkdocs build：編譯 site/docs/ → public/
  5. （Stage 2）部署 public/ 至 Cloudflare Pages

本地開發

# 首次同步（需要 yq：brew install yq）
bash scripts/sync-docs.sh

# 啟動本地預覽（http://localhost:8000，支援 hot reload）
docker compose up docs

# 部署 workspace 設定到本地工作目錄
bash scripts/deploy-config.sh

命名規範

• scripts/ 下的腳本一律使用 kebab-case（如 sync-docs.sh）
• workspace/.claude/commands/ 下的 Skills 一律使用 kebab-case（如 commit.md）
• repos.yml 中的 name 欄位必須與本地工作目錄中的資料夾名稱一致