Markdown for mdsvr 技能（Markdown for mdsvr Skill）
為 mdsvr 生成完整、有效、多檔案的 Markdown 文件集 —— 支援伺服器模式與靜態匯出。
當觸發此技能時，請產出多個 .md 檔案，形成一個有條理的文件網站，並嚴格遵循所有 mdsvr 慣例。
步驟 1 — 理解需求
在生成檔案之前，從使用者的需求中提取以下資訊：
- 主題 / 產品名稱 — 要記錄什麼？
- 目標受眾 — 開發人員、終端使用者、營運團隊等。
- 範圍 — 需要多少頁面 / 章節？
- 語言 — 中文、英文或雙語？
- 是否需要圖表？ — 如果是，請閱讀
references/rules/mermaid.md以了解語法規則。
如果以上任何一項不清楚，請在繼續之前提出一個明確的問題。
步驟 2 — 規劃檔案結構
在撰寫內容之前，先設計一個邏輯層級結構。一個典型的 mdsvr 文件網站範例如下：
docs/
├── README.md ← 首頁（必要）
├── 01-getting-started/
│ ├── README.md ← 章節索引
│ ├── 01-installation.md
│ ├── 02-quickstart.md
│ └── 03-configuration.md
├── 02-guides/
│ ├── README.md
│ ├── 01-basic-usage.md
│ └── 02-advanced.md
├── 03-api-reference/
│ ├── README.md
│ └── 01-endpoints.md
└── 04-troubleshooting.md
根據使用者的主題調整結構，並視需要增減規模。
步驟 3 — 套用 mdsvr 檔案與連結規則（強制）
3.1 檔案命名規則
| 規則 | ❌ 錯誤範例 | ✅ 正確範例 |
|---|---|---|
| 名稱中間不可有句點 | 0.1.quickstart.md | 01-quickstart.md |
| 名稱中間不可有句點 | config.v2.md | config-v2.md |
| 使用連字號（kebab-case） | GettingStarted.md | getting-started.md |
| 使用數字前綴排序 | guide.md（在側邊欄中） | 01-guide.md |
| 描述性名稱 | page1.md | installation.md |
| 目錄索引必須為 | index.md | README.md |
3.2 連結結構規則
| 規則 | ❌ 錯誤範例 | ✅ 正確範例 |
|---|---|---|
| 僅使用相對路徑 | [指南](/docs/guide) | [指南](./guide) |
連結中不要有 .md 副檔名 | [設定](./setup.md) | [設定](./setup) |
| 連結到目錄，而非 README | [開始](./01-getting-started/README) | [開始](./01-getting-started) |
| 錨點連結必須與標題相符 | [請參閱](#install-steps)（如果標題不存在） | 完全相符 |
3.3 標題結構規則
| 規則 | ❌ 錯誤範例 | ✅ 正確範例 |
|---|---|---|
| 每個頁面都需要 H1 | （頁面以 H2 開頭） | # 頁面標題 作為第一個標題 |
| 不要跳過標題層級 | H1 → H3 | H1 → H2 → H3 |
| 標題必須具有描述性 | ## 章節 1 | ## 安裝需求 |
步驟 4 — 為每個檔案添加前置元資料（Frontmatter）
每個 .md 檔案必須包含 YAML 前置元資料，用於 SEO 和 mdsvr 元資料：
---
title: "頁面標題"
description: "此頁面內容的一句話描述。"
---
步驟 5 — 內容撰寫指南
README.md（首頁）— 必要
- 必須存在於文件資料夾的根目錄。
- 包含：專案概覽、連接到所有章節的快速導覽連結。
- 如有需要，可使用歡迎提示框。
章節 README.md（目錄索引）
- 總結該章節涵蓋的內容。
- 列出該章節中的所有頁面，並附上相對連結。
內容頁面
- 每個頁面專注於一個主題。
- 以簡短的介紹段落開始。
- 在適當時使用 MDX 元件：
:::note、:::warning、:::tip、:::danger用於提示框。- 對於逐步操作流程，使用編號清單。
- 使用相對路徑自由連結到相關頁面。
- 在有用時，以「後續步驟」或「相關主題」章節結尾。
步驟 6 — Mermaid 圖表（必要時）
如果文件需要圖表（架構圖、流程圖、序列圖、實體關係圖、狀態機圖等），請在相關的 .md 檔案中內嵌 Mermaid 圖表。
在生成任何圖表之前，請閱讀
references/rules/mermaid.md以取得完整的語法參考和生成規則。該檔案中的所有規則都是強制性的。
快速檢查清單（來自 mermaid.md）：
- 選擇最合適的圖表類型 —— 不要預設使用
flowchart。 - 在流程圖中始終宣告方向：
flowchart TD或flowchart LR。 - 節點 ID：僅限字母、數字、底線。不能使用
-、.、(、)。 - 包含空格的節點標籤必須使用雙引號：
A["我的標籤"]。 - 子圖必須有明確的 ID：
subgraph myid["標籤"]。 - 序列圖：在訊息之前宣告所有
participant行。 - 除非使用者明確要求，否則不要使用硬編碼的顏色或樣式。
- 使用表情符號代替顏色來傳達語義含義。
- 每個程式碼區塊一個圖表；在輸出之前驗證語法。
步驟 7 — 建立檔案並交付
使用 create_file 將每個 .md 檔案寫入檔案系統。然後壓縮所有檔案並呼叫 present_files，以便使用者可以下載結果。
7.1 寫入每個檔案
對於規劃結構中的每個檔案，呼叫 create_file，並使用 /mnt/user-data/outputs/<專案名稱>/ 下的完整路徑：
/mnt/user-data/outputs/my-project/README.md
/mnt/user-data/outputs/my-project/01-getting-started/README.md
/mnt/user-data/outputs/my-project/01-getting-started/01-installation.md
...
在每次呼叫中寫入完整的最終內容 —— 不要寫入佔位符。
7.2 壓縮並顯示
在所有檔案寫入完成後，壓縮輸出資料夾並呼叫 present_files：
cd /mnt/user-data/outputs
zip -r my-project-docs.zip my-project/
然後使用 .zip 檔案的路徑呼叫 present_files。
7.3 在對話中總結
在呼叫 present_files 之後，在對話中寫一條簡短訊息，包含：
- 檔案樹 — 顯示生成的完整目錄結構。
- 如何執行 — 一行指令：
npx mdsvr ./my-project或mdsvr ./my-project。 - 頁面數量 — 例如「已生成 8 個頁面，分佈於 3 個章節。」
快速參考 — 應避免的常見錯誤
❌ 連結中使用絕對路徑： [頁面](/docs/page)
✅ 使用相對路徑： [頁面](./page)
❌ 連結中使用 .md 副檔名： [頁面](./page.md)
✅ 不使用副檔名： [頁面](./page)
❌ 連結到 README 檔案： [章節](./01-section/README)
✅ 連結到目錄： [章節](./01-section)
❌ 檔案名稱中有句點： 01.quickstart.md
✅ 使用連字號分隔： 01-quickstart.md
❌ 缺少 H1： ## 簡介 （第一個標題是 H2）
✅ 以 H1 開頭： # 簡介
❌ 跳過標題層級： # 標題 → ### 子章節（跳過 H2）
✅ 正確的層級結構： # 標題 → ## 章節 → ### 子章節
❌ 沒有前置元資料： (檔案直接以 # 開頭)
✅ 有前置元資料： --- title: "..." description: "..." ---
參考檔案
references/rules/mermaid.md— 所有 19 種圖表類型的完整 Mermaid v11 語法參考。每當文件中需要任何圖表時，請閱讀此檔案。