CloudyWing/check-markdown

check-markdown

當使用者要求「檢查 Markdown」、「修正格式」或「整理文件」時，或是目標檔案為 .md / .mdx，請自動套用本技能。

執行步驟

1. 辨識文件平台

依優先順序偵測：

| 偵測目標 | 判定平台 | | --- | --- | | package.json 含 vitepress 依賴 | VitePress | | .vitepress/ 目錄存在 | VitePress | | docusaurus.config.js 存在 | Docusaurus | | mkdocs.yml 存在 | MkDocs (Material) | | 以上皆無 | GitHub Flavored Markdown（預設） |

若偵測到多個平台特徵，以 package.json 依賴為準。

2. Alert / Callout 語法對照

| 平台 | 語法格式 | | --- | --- | | GitHub | > [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION] | | VitePress | ::: info、::: tip、::: warning、::: danger、::: details | | Docusaurus | :::note、:::tip、:::warning、:::danger、:::info | | MkDocs | !!! note、!!! tip、!!! warning、!!! danger、!!! info |

3. 通用格式檢查

無論平台皆須檢查：

• 程式碼區塊內容絕對保留原樣：``` 圍起的程式碼區塊、行內 ` 反引號包覆的內容、命令、路徑、版本號一律不修改，僅修正區塊外的格式問題。此為所有格式規則的最高原則。
• 標題層級：文件應有且僅有一個 # H1，後續使用 ## ~ ####。
• 空行規則：標題、清單區塊、程式碼區塊前後各保留一個空行。
• 連結格式：無斷裂連結（[text]() 或 [](url) 為錯誤）。
• 圖片替代文字：![alt](url) 中 alt 不應為空。
• 清單縮排：巢狀清單使用一致的縮排（2 或 4 空格）。
• 程式碼區塊語言：``` 後應指定語言標記。

4. 清單符號規則

• 原檔案已統一：全 - 或全 * 則尊重原檔案，不更改。
• 混用情況：- 與 * 混用，統一改為 -。
• 新產生的清單：預設使用 -。

5. 清單結尾符號規則

不加結尾符號（純列舉型）：

• 名詞、工具名、URL、版本號、路徑、程式碼識別字列舉

需加結尾符號（說明型）：

• 含動詞或構成完整句子 → 中文用 。，英文用 .
• 步驟描述、補充說明等敘述型內容

6. 表格格式規則

• 分隔列格式：| --- | 而非 |---|（前後各一空格）。
• 掃描所有表格分隔列並補上缺少的空格。

6.5 中英文夾排與標點

中英文間距

• 中文字與英文字母／數字之間，必須有一個半形空格。
  • ❌ C#的IDisposable介面是.NET 6引入的
  • ✅ C# 的 IDisposable 介面是 .NET 6 引入的
• 反引號包覆的程式碼識別字（`IDisposable`）視同英文處理，前後與中文之間需空格。

標點符號全形/半形

• 中文語境：使用全形標點 ，。：；「」（）。
• 英文語境：使用半形標點 ,.;:"()。
• 不混用：同一段落中，中文與英文標點不混用。
• 例外：程式碼區塊與反引號內的內容保留原樣，不套用此規則。

6.6 散文式冒號接續

段落正文中不使用「X：Y」的散文式冒號接續句式（X 為引言，Y 為接續的散文詳述）。改用句號拆成兩句陳述。

• ❌ 這是一個關鍵概念：所有請求都會經過驗證層。
• ✅ 這是一個關鍵概念。所有請求都會經過驗證層。

例外（保留，不視為違規）：

• 引導結構化內容：設定如下：、步驟如下：（後接清單、表格或程式碼區塊）。
• 例子引導：例：、例如：。
• 標籤型欄位：適用情境：...、限制：...、某某某：說明。

此規則需語意判斷以區分散文接續與合法的標籤／引導用法，無法用 regex 機械化，須逐段判讀。程式碼區塊與反引號內的內容不套用。

6.7 全形破折號

段落正文中不使用全形破折號 ——（連續兩個 U+2014）作為句中轉折，改用逗號、分號或拆成獨立句子。

• ❌ 這個設計有風險——它假設輸入永遠合法。
• ✅ 這個設計有風險，它假設輸入永遠合法。

寫檔後由 post-edit-write hook 機械掃描 .md 檔的 ——；程式碼區塊與反引號內的內容保留原樣，不套用此規則。

7. 平台特定注意事項

• VitePress：frontmatter (---) 格式須正確；::: 語法格式保留原樣，不改為 > [!...]；Vue 元件語法照原樣保留。
• Docusaurus：MDX 語法（import、export）不得誤修正；Admonitions 使用 ::: 語法。
• GitHub：Task list (- [ ] / - [x]) 保持不變。

7.5 清單縮排與間距

• 清單符號後方：- 或 * 後方恰好一個半形空格，不多不少。
• 巢狀縮排：統一使用 2 個空格進行巢狀縮排，不使用 3、4 或更多空格。
• 項目間空行：
  • 同層級的簡短清單項目之間不插入空行。
  • 僅當項目內部包含多段落或程式碼區塊時，該項目前後才允許空行。
• 尾端空格：清單項目行末不留 trailing whitespace。

8. 執行流程

1. 列出所有偵測到的問題。
2. 詢問使用者確認後進行批次修正。
3. 修正時保留原始語意，僅調整格式。