check-markdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# check-markdown

## 執行步驟

### 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. 列出所有偵測到的問題。

From CloudyWing/ai-dotfiles, MIT.

More from CloudyWing/ai-dotfiles