markdown linting accessibility 風格指南 documentation

Markdown 檢查指南:15 個常見問題及修正方法

查詢並修復常見的 Markdown 問題,包括跳過標題、丟失影像替代文本、裸 URL、損壞的程式碼圍欄、不一致的列表和格式錯誤的表格。

W
WordToMD 團隊
·

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. 沒有替代文本的影像

問題

![](architecture.png)

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

修復

![Request flow from the browser through the API gateway to the orders service](architecture.png)

描述影像提供的資訊,而不僅僅是其外觀。除非媒介很重要,否則避免使用“image of”之類的短語。

裝飾影像是一個特例。當影像不傳達資訊時,“HTML”中的空替代文本可能是正確的,但“Markdown”渲染器和內容工作流程有所不同。如果影像純粹是裝飾性的,首先詢問它是否屬於技術文件。

linter Markdown帶有空替代文本的 ¤T​​000¤ 影像。的 圖片格式化工具 可以生成具有顯式替代和可選標題的影像標記。

問題

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.

在採用延期之前,請回答三個問題:

  1. 哪個渲染器擁有最終輸出?
  2. 內容稍後需要移至其他地方嗎?
  3. 當擴充套件不受支援時,讀者會看到什麼?

保留可移植的 Markdown 基礎,並儘可能在釋出邊緣新增平臺語法。

實用的 Linting 工作流程

步驟 1:檢查結構

將原始碼貼上到 Markdown 規範檢查。首先修復錯誤,然後修復警告,然後修復資訊一致性專案。自動檢查應識別位置;他們不應該默默地重寫意義。

步驟 2:標準化困難元素

使用專用工具進行機械清理:

與重寫整個檔案的廣泛格式化程式相比,集中更改會產生更小、更易於檢視的差異。

步驟 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”在未來的編輯中更加便攜、易於訪問和可靠。