前言
之前在〈把設計文件用 Markdown 管理，並自動轉換成 PDF 吧！〉這篇文章中，我介紹了以 Markdown 管理設計文件的做法。
這裡則是作為延伸，進一步具體整理一個構成：將以 Markdown 管理的設計文件以 HTML 形式公開，並同時考慮在 GitHub 上的審查，以及 AI 的活用。
動機
我們團隊目前是用 Confluence 來管理設計文件。
編輯與瀏覽都很方便，日常運作上也沒有遇到太大的困擾。不過，當想要透過 AI 來參照設計文件、產生修改提案，或是上傳後更新時，就會碰到幾個不便之處。
- 透過 MCP 取得與更新的成本較高
- 設計文件本文與圖表不容易一起處理
- 差異不容易以程式碼審查的流程來檢視
因此，我嘗試規劃一個以 GitHub 上好處理的 Markdown 為基礎，同時盡量不要降低人類閱讀時可讀性的架構。
實作內容
- 將設計文件交由 GitHub 管理
- 透過 GitHub Actions 自動產生 HTML 頁面，並在 GitHub Pages 上公開
- 以 PR 為單位也生成 HTML 頁面，方便確認外觀
建立的架構
為了驗證，我做了一個把 Markdown 設計文件網站化的範例，使用的是 MkDocs Material。
拿來驗證的範例也已經公開在 GitHub 上。
大致上的架構如下。
mkdocs.yml
requirements.txt
package.json
.github/workflows/pages.yml
docs/
index.md
architecture/sample-ec-service.md
assets/images/sample-system-context.svg
scripts/
write-version.mjs整理一下各自的角色如下。
檔案角色mkdocs.yml主題、導覽、Markdown 擴充設定docs/**/*.md設計文件本文docs/assets/images/*圖片資源.github/workflows/pages.yml發佈到 GitHub Pages 的流程如下圖所示。
MkDocs 是什麼
MkDocs 是一個將 Markdown 文件轉換成靜態 HTML 網站的工具。
這裡會使用它來將設計文件轉成 HTML。它和 GitHub Pages 這類靜態託管服務也很搭，整體架構相對簡單。
MkDocs 本身是用來從 Markdown 產生網站的基礎。在它上面套用的主題則使用 Material for MkDocs。
Material for MkDocs 的特色不只是外觀，也很容易強化搜尋、導覽、目錄、日文支援等功能。因為它很容易整理成對人類友善的文件網站，所以我選了它。
本文管理
設計文件本文就直接以 Markdown 放在 docs/ 底下。
用 Markdown 管理的話，本文的變更會直接成為 Pull Request 的差異。
例如，非功能需求的表格，用一般的 Markdown 就已經足夠了。
| 分類 | 要求 | 補充 |
| --- | --- | --- |
| 可用性 | 每月可用率 99.9% | 將 CDN 與 Backend API 做冗餘設計 |
| 效能 | 商品搜尋 P95 低於 500ms | 善用快取 |
| 安全性 | 管理介面必須使用 SSO | 保存稽核紀錄 |圖與圖片的處理
設計文件中圖表也很重要。過去我們常用 PlantUML，但因為無法直接在 GitHub 上顯示，所以改採 Mermaid。
雖然也有考慮過把 PlantUML 動態轉成 SVG 再顯示，但那樣會變成要轉成 HTML 之後才能確認，比較不方便。因為我希望在 GitHub 上就能直接看見，也比較容易追蹤差異，所以優先選擇 Mermaid。
種類適合用途管理方式Mermaid架構圖、流程圖、循序圖直接寫在 Markdown 內圖片檔畫面截圖、既有資料放在 docs/assets/images/Mermaid 或圖片都能直接在 GitHub 上顯示，因此在倉庫中閱讀設計文件時也很方便。
本機確認
在本機可以用以下方式建置。
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm test
python3 -m http.server 8000 -d site發佈到 GitHub Pages
當合併到 main 分支後，會透過 GitHub Actions 建置網站並發佈到 GitHub Pages。
workflow 也支援 push / PR / 手動執行。
on:
push:
branches: [main]
pull_request:
types: [opened, reopened, synchronize, closed]
workflow_dispatch:對 main 的 push 會更新 production，PR 則會公開 preview。
PR 時的預覽顯示
光看 Markdown 的差異也能審查，但像下面這些排版問題，不看 HTML 很難注意到。
- Mermaid 或圖片顯示異常
- 圖片連結失效
- 表格寬度
- 在導覽中的呈現方式
因此，我改成每個 PR 都公開一個 preview。PR 會把建置好的網站放到 gh-pages 分支的 /previews/pr-<PR編號>/ 底下，讓差異審查和外觀確認可以分開進行。
實作上，是透過 GitHub Actions 將建置好的網站部署到 PR 對應的路徑，再由 workflow 組出 preview URL，自動寫進 PR 留言裡。同時，如果能從側邊欄連到該 preview 頁面，就更容易和 production 對照查看。
production:
https://<owner>.github.io/<repo>/
PR preview:
https://<owner>.github.io/<repo>/previews/pr-<PR編號>/PR 的流程如下。
preview 的公開是使用 gh-pages 分支的子目錄，並且也會在 PR 留言中顯示 URL。如果有需要，也可以同時更新 preview 清單與側邊欄，讓導引更完整。
這一段有些地方是用 workflow 和 script 比較偏土法煉鋼的方式處理，所以直接看實際檔案會最快。
組合 Preview 頁面 URL 的 workflow```
- name: Compute preview URL
id: preview_url
env:
OWNER: ${{ github.repository_owner }}
REPO: ${{ github.event.repository.name }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
if [ "$REPO" = "$OWNER.github.io" ]; then
BASE_URL="https://$OWNER.github.io"
else
BASE_URL="https://$OWNER.github.io/$REPO"
fi
echo "url=$BASE_URL/previews/pr-$PR_NUMBER/" >> "$GITHUB_OUTPUT"
將 preview URL 寫入 PR 留言的 workflow```
- name: Comment preview URL
uses: actions/github-script@v7
env:
PREVIEW_URL: ${{ steps.preview_url.outputs.url }}
with:
script: |
const body = [
'### Design Docs Preview',
🔎 **Preview:** ${process.env.PREVIEW_URL},
].join('\n');
實際上，我是讓 workflow 自動在 PR 留言中貼上 preview URL 與 version index 的連結。
從留言打開 preview 頁面後，就能直接確認產生出來的 HTML。
注意事項
GitHub Pages 的設定
若要透過 URL 顯示 PR preview，就需要先將 GitHub Pages 設為以 branch-based 方式啟用。
Settings > Pages > Build and deployment
Source: Deploy from a branch
Branch: gh-pages
Folder: / (root)來自 fork 的 PR
同一個倉庫內的 PR 處理起來比較簡單，但來自 fork 的 PR 就需要注意權限與 secret 的使用。
這種情況下，也可以考慮不公開 preview，只保留 artifact 的構成，我認為這也是可行的。
結語
如果你希望設計文件同時容易被 AI 處理，又能維持人類閱讀時的可讀性，我認為 Markdown + MkDocs Material + GitHub Pages 是很值得嘗試的組合。
如果你有興趣，不妨先從一份小型設計文件開始試試看。
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
