Markdown 是允許的。存在結構錯誤的文件仍可能會呈現,這使得這些錯誤很容易被忽略,直到表格損壞、標題從導航中消失或影像對螢幕閱讀器使用者來說變得毫無意義。
Markdown linting 是在釋出之前檢查源文本結構、可訪問性和一致性問題的過程。從 Markdown 規範檢查 捕獲跳過的標題級別、丟失的影像替代文本、裸露的 URL、未標記或未封閉的程式碼圍欄以及尾隨空白。然後使用本指南中的手動檢查表進行更廣泛的編輯審查。
Linting 並不是強制執行任意偏好。有用的規則應該防止真正的讀取、渲染、維護或可訪問性問題。
快速釋出前清單
| 檢查 | 為什麼它很重要 | 自動還是手動? |
|---|---|---|
| 標題層次結構 | 保留文件結構 | 短絨 |
| 圖片替代文本 | 使影像無需視覺即可理解 | 短絨 |
| 描述性連結 | 改進可訪問性和掃描 | Linter + 手動審查 |
| 封閉式程式碼圍欄 | 防止頁面的其餘部分成為程式碼 | 短絨 |
| 程式碼語言標籤 | 啟用有用的語法突出顯示 | 短絨 |
| 尾隨空格 | 避免隱形的、特定於方言的行為 | 短絨 |
| 一個清晰的頁面標題 | 保持頁面目的明確 | 人工稽核 |
| 一致的列表 | 防止巢狀破損 | 人工稽核 |
| 有效表格 | 保持柱結構完整 | 人工稽核 |
| 獨特的標題 | 防止重複錨混淆 | 人工稽核 |
| 行動式HTML 使用 | 避免特定於渲染器的故障 | 人工稽核 |
| 可讀段落 | 提高理解力 | 人工稽核 |
將代表性文件貼上到 linter 中,執行檢查,修復報告的行,然後在實際釋出系統中預覽完整頁面。
1. 跳過標題級別
問題
# Deployment Guide
### Configure credentials
文件從 H1 跳轉到 H3。當字型大小是唯一可見的訊號時,它看起來可能是可以接受的,但結構輪廓缺少一個層次。
修復
# Deployment Guide
## Configure credentials
使用標題來描述層次結構,而不是選擇視覺大小。如果“配置憑據”確實屬於缺失的部分,請新增該部分:
# Deployment Guide
## Preparation
### Configure credentials
的 Markdown 規範檢查 報告跳轉超過一級的標題。
2. 多個或缺失的 H1 標題
一頁通常應有一個清晰的標題。一些文件系統從前面的內容生成 H1,而其他文件系統則期望它在“Markdown”正文中。瞭解您的網站使用哪種約定。
來源不明確
# Installation
# Configuration
清晰來源
# Product setup
## Installation
## Configuration
如果您的網站模板呈現 title: Product setup 作為頁面 H1,正文可以改為以 H2 開頭。規則不是“每個 Markdown 檔案必須恰好包含一個 #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. 僅用於強調的標題
此源建立了不必要的大綱條目:
#### Important!
如果文本沒有介紹某個部分,請使用散文或適當的標註:
**Important:** Back up the database before continuing.
標題應該幫助讀者導航。裝飾性標題會使目錄變得嘈雜,並降低輔助導航的實用性。
4. 沒有替代文本的影像
問題

該影像沒有替代文本。看不到它的讀者不會收到任何解釋,瀏覽損壞或停用影像的人也無法確定其目的。
修復

描述影像提供的資訊,而不僅僅是其外觀。除非媒介很重要,否則避免使用“image of”之類的短語。
裝飾影像是一個特例。當影像不傳達資訊時,“HTML”中的空替代文本可能是正確的,但“Markdown”渲染器和內容工作流程有所不同。如果影像純粹是裝飾性的,首先詢問它是否屬於技術文件。
linter Markdown帶有空替代文本的 ¤T000¤ 影像。的 圖片格式化工具 可以生成具有顯式替代和可選標題的影像標記。
5. 薄弱或裸連結
問題
Visit https://example.com/docs/setup for more information.
裸露的 URL 很難掃描,而且大聲朗讀時可能會令人不愉快。通用連結文本也好不了多少:
[Click here](https://example.com/docs/setup).
修復
Read the [service setup guide](https://example.com/docs/setup).
描述性連結告訴讀者他們將開啟什麼。當它們被提取到連結列表中時也仍然有意義。
linter 識別出許多裸露的 http:// and https:// URL,但仍需要編輯審查來判斷連結文本是否有用。
6. 未封閉的程式碼圍欄
問題
```javascript
const status = 'ready';
## Next section
如果沒有關閉圍欄,渲染器可能會將頁面的其餘部分視為程式碼。
修復
```javascript
const status = 'ready';
```
## Next section
未封閉的柵欄可能會破壞原本有效的文件的大部分。linter 報告不匹配柵欄開始的行。
7. 沒有語言識別符號的程式碼圍欄
不太有用
```
npm run build
```
更好
```bash
npm run build
```
語言識別符號支援語法突出顯示並傳達讀者正在看到的內容型別。使用通用識別符號,例如 javascript, typescript, json, html, css, bash, powershell, yaml,或 markdown.
不要僅僅為了獲得顏色而新增不準確的語言。對於非結構化輸出,請使用 text 當目的地識別它時。
8. 列表縮排不一致
問題
- Install dependencies
- Production packages
* Development packages
- Optional tools
混合製表符、空格和標記很難檢視,並且可能會在不同級別上呈現。
修復
- Install dependencies
- Production packages
- Development packages
- Optional tools
為專案選擇一致的縮排寬度。空格的確切數量可能取決於“Markdown”方言和列表內容,但一致性至關重要。
使用 巢狀清單格式化工具 在最終稽核之前規範混合專案符號、編號、製表符和縮排。
9. 手動輸入數字序列
長編號列表的維護成本很高:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
許多Markdown渲染器允許每個專案使用 1. 同時仍然顯示有序序列:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
這減少了源差異中的重新編號噪音。然而,當說明提到“步驟 3”時,明確編號的來源更容易討論。選擇一種專案慣例並一致地應用它。
不要組合鍵入的數字、有序列表標記和段落文本。編輯巢狀步驟後確認渲染結果。
10. 格式錯誤的表格
問題
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
分隔符和資料行不包含相同的邏輯列數。
修復
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
還要檢查單元格內的未轉義管道字元:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
的 Markdown 表格格式化工具 有助於暴露不均勻的行併產生對齊的源。要直觀地建立新表,請使用 Markdown 表生成器.
11. 重複標題和錨點衝突
文件可以合法地重複可見標題,例如“示例”,但自動生成的錨點 ID 可能會變成 #examples, #examples-1,以及 #examples-2。確切的規則因渲染器而異。
重複的標題使手動連結變得脆弱:
- [API examples](#examples)
- [CLI examples](#examples)
更喜歡描述性標題:
## API examples
## CLI examples
然後生成一個目錄 Markdown TOC 發生器 並驗證目標平臺中的錨點。
12. 尾隨空白
行尾的空格是不可見的。在某些“Markdown”方言中,兩個尾隨空格會建立硬換行符,這意味著意外的編輯器操作可能會更改呈現。
linter 報告尾隨空白,以便您可以確定它是否是故意的。最好用空行來分隔段落。如果確實需要嚴格的換行,請一致地記錄並應用專案所選擇的約定。
編輯器通常可以在儲存時自動刪除尾隨空格,但請檢查這不會更改舊內容中的有意換行符。
13. 降低可移植性的原始HTML
Markdown 通常允許嵌入 HTML:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
該塊可能在一個網站上有效,但在其他地方會被轉義、清理或設定錯誤的樣式。當可以表達相同含義時,首選行動式Markdown:
> **Warning:** Restarting the service ends active sessions.
故意使用 HTML 來表示 Markdown 無法表達的功能,例如受控的影像尺寸或支援的 <details> 塊。保留內容必須呈現的目的地列表並測試每個目的地。
的 標註生成器 可以為 GitHub、Obsidian 和 MkDocs 生成特定於平臺的語法。
14. 段落過長且易讀性差
Markdown在結構上可能是有效的,但仍然難以閱讀。包含多項決定、警告和程式的文本牆應該重新組織。
使用:
- 一個主要思想的短段落;
- 導航描述性標題;
- 平行專案列表;
- 真正可比欄位的表格;
- 用於文字輸入和輸出的程式碼塊;
- 少量重要異常的標註。
不要把每句話都變成子彈。當專案具有相同的語法和概念角色時,列表效果最佳。
使用 字數統計與閱讀時間 檢查段落數、標題數和閱讀長度,但將統計資料視為訊號而不是目標。
15. 沒有相容性計劃的渲染器特定語法
GitHub 任務列表、Obsidian wiki 連結、MkDocs 警告、腳註、定義列表和前言都很有用,但並非所有地方都支援它們。
例如:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
在採用延期之前,請回答三個問題:
- 哪個渲染器擁有最終輸出?
- 內容稍後需要移至其他地方嗎?
- 當擴充套件不受支援時,讀者會看到什麼?
保留可移植的 Markdown 基礎,並儘可能在釋出邊緣新增平臺語法。
實用的 Linting 工作流程
步驟 1:檢查結構
將原始碼貼上到 Markdown 規範檢查。首先修復錯誤,然後修復警告,然後修復資訊一致性專案。自動檢查應識別位置;他們不應該默默地重寫意義。
步驟 2:標準化困難元素
使用專用工具進行機械清理:
- 巢狀清單格式化工具 用於縮排;
- Markdown 表格格式化工具 用於管道表;
- 圖片格式化工具 用於影像標記;
- 目錄產生器 用於航向錨。
與重寫整個檔案的廣泛格式化程式相比,集中更改會產生更小、更易於檢視的差異。
步驟 3:預覽文件
開啟原始碼 Markdown 編輯 並將 Markdown 與渲染輸出進行比較。檢查:
- 標題和目錄;
- 列表和任務列表;
- 窄螢幕上的表格;
- 影像和連結;
- 程式碼塊和內聯程式碼;
- 標註或原始HTML。
步驟 4:測試真實目的地
通用預覽無法重現每個渲染器。在釋出之前,在GitHub、Obsidian、GitLab、MkDocs 或實際文件站點中開啟檔案。
步驟 5:回顧含義,而不僅僅是語法
沒有 linter 可以確定程式是否安全、指向預期策略的連結或影像描述是否傳達重要結論。人工審閱者應確認準確性、完整性、語氣和受眾契合度。
團隊風格指南建議
一個簡短的書面約定比幾十個不言而喻的偏好更有效。定義:
- 頁面標題是否位於前面內容或“Markdown”正文;
- 允許的航向進展;
- 列表縮排和有序列表樣式;
- 程式碼圍欄語言要求;
- 如何審查影像和替代文本;
- 表複雜性限制;
- 允許HTML和平臺擴充套件;
- 最大線長度(如果團隊使用一條線);
- 如何檢查連結;
- linter 規則阻止釋出。
從防止真正缺陷的規則開始。僅當團隊瞭解其解決的問題時才新增規則。
FAQ
有效的Markdown 是否可以自動訪問?
否。有效的語法仍然可能包含空的替代文本、模糊的連結、令人困惑的標題、難以訪問的圖表和糟糕的閱讀順序。可訪問性需要結構和編輯審查。
Markdown Linter 會重寫我的文件嗎?
WordToMD linter 報告行號問題。它不會默默地重寫原始碼,因此您可以保留對每次更正的控制。
為什麼 linter 報告一個裸 URL?
描述性連結文本更易於掃描,對輔助技術更有用。將 URL 替換為有意義的標籤,除非文字地址是讀者需要的資訊。
未標記的程式碼圍欄總是錯誤的嗎?
並不總是如此,但正確的語言識別符號通常可以提高畫質晰度和語法突出顯示。使用 text 用於在受支援時進行純輸出,而不是分配不準確的程式語言。
所有專案都應該使用相同的 linting 規則嗎?
否。“GitHub”、“README”、“Obsidian”保管庫、“API”參考和釋出站點具有不同的約定。共享一組核心結構和可訪問性規則,然後新增特定於目的地的檢查。
linting 可以代替校對嗎?
否。linter 檢測模式。它無法可靠地驗證技術真相、論證質量、使用者意圖或句子在上下文中是否可以理解。
結論
好 Markdown 不僅僅是恰好渲染的源。它具有清晰的輪廓、有意義的連結、可訪問的影像、完整的程式碼圍欄、一致的列表、有效的表格以及與其釋出平臺的明確關係。
執行 Markdown 規範檢查 對於快速結構檢查,請使用 Markdown 編輯 用於視覺審查,並僅在使原始碼更易於維護的地方應用集中格式化程式。結果是“Markdown”在未來的編輯中更加便攜、易於訪問和可靠。