Markdown教程如何展示三反引號：嵌套代碼圍欄的寫法

開始前先確認

要正確展示嵌套的三反引號代碼塊，可先考慮兩種常用方法：使用比內層標記數量更長的外層圍欄（通常爲四個反引號），或者使用經典的 4 空格縮進代碼塊語法。

核心機制：圍欄式代碼塊的解析規則

Markdown 解析器在處理代碼圍欄（Fenced Code Blocks）時，依據行首的反引號（`）或波浪號（~）來識別代碼邊界。

根據規範定義（參見 CommonMark 規範：閉合標記需使用相同符號且長度不短於開啓標記），外層圍欄的字符類型與長度決定了代碼塊何時結束。這意味着：如果外層使用四個連續反引號開啓代碼塊，那麼在其內部出現的一組、兩組或三組連續反引號都僅會被視作純文本字符；只有遇到同樣由四個或更多連續反引號構成的獨立行時，外層代碼塊纔會閉合。

掌握這一機制後，嵌套展示代碼圍欄就不再需要依賴複雜的字符轉義。

常用寫法與具體實現步驟

根據目標平臺的支持情況，主要有以下三種實現方案：

方案一：使用四個反引號作爲外層圍欄（推薦）

這是撰寫 Markdown 教程時最常用、可讀性最好的方式。外層使用四個反引號（`），内层使用三个反引号（），並在外層或內層按需標註語言標籤。

在原始 Markdown 文檔中書寫如下內容：

````markdown
```python
def process_data(records):
    # 处理文件记录
    return len(records)
```
````

解析效果說明： 渲染器會把四個反引號之間的所有內容（包括內層的三反引號及 Python 示例代碼）作爲一個整體代碼塊輸出，讀者能清晰看到三反引號的完整結構。

> 規則拓展：如果教程需要演示四個反引號本身的用法，外層只需遞增到五個反引號；依此類推，外層長度始終保持嚴格大於內層最長標記即可。

方案二：使用波浪號（~）作爲外層圍欄

CommonMark 規範同樣允許使用三個或更多波浪號（~~~）建立代碼圍欄。反引號與波浪號屬於不同的符號類型，彼此互不干擾。

在原始 Markdown 文檔中書寫：

~~~markdown
```bash
# 启动本地服务
npm run dev
```
~~~

適用場景：當文檔片段中包含多種反引號且層級複雜時，採用波浪號作爲外圍邊界可以顯著降低符號混淆的概率。

方案三：使用 4 空格縮進語法

在標準 Markdown 體系中，頂層內容縮進四個空格可形成縮進代碼塊；前面需要適當段落邊界，列表中的相對縮進另行覈對。Tab 會按製表位展開，不能簡單假定任意位置都等於四格。

在原始 Markdown 文檔中書寫：

    ```json
    {
      "status": "success",
      "code": 200
    }
    ```

適用場景：適用於極爲精簡的純文本環境。但需要注意，縮進語法通常無法在代碼塊頂部聲明語言標籤以實現語法高亮。

方案選型與交付覈對清單

爲了在文檔交付前確認排版表現，可通過下表評估不同方案的技術差異：

交付前核對清單（Checklist）

在技術文檔、教程交付或發佈前，建議逐項覈實以下內容：

• [ ] 圍欄長度覈對：檢查外層標記數量是否嚴格多於內部出現的最長圍欄長度。
• [ ] 符號配對一致性：確認外層的開啓行與閉合行使用的是同一種字符（不可開頭用反引號、結尾用波浪號）。
• [ ] 目標渲染器確認：明確文檔最終交付的目標發佈系統（如 GitHub、自建靜態文檔庫或特定 CMS），避免特定引擎對四反引號支持不全造成排版坍塌。
• [ ] 交互與標記兼容性：若交付文檔中同時包含任務列表等排版元素，可參考 Markdown複選框兼容性 確認各終端解析規則是否一致。
• [ ] 相對路徑覈驗：檢查示例中引用的資源與鏈接路徑是否有效，可結合 Markdown相對鏈接檢查 規範進行逐一排查。

假設性交付場景：識別顯示差異與真實數據

設想一個日常文件交付場景：技術文檔編寫人員需要向運營團隊交付一份《代碼規範指引》Markdown 原稿。

在編寫人員的本地編輯環境中，文檔使用了四個反引號來包裹 Python 示例。然而在交付到未完整實現 CommonMark 規範的內部舊版工單系統預覽時，出現了明顯的解析異常：

• 異常現象：該系統未能識別四個反引號構成的外圍標記，直接把首行字符逐字打印在正文中，而將內層的第一個三反引號錯誤識別爲開啓標記，導致後續整屏文字均被陰影背景覆蓋。
• 排查與修正：覈對人員發現該特定渲染器僅支持三反引號與縮進代碼塊。編寫人員隨即切換爲“4 空格縮進方案”重新導出，再檢查渲染結果與複製出的代碼是否一致；這個例子不是實際測試記錄。

這一過程表明：代碼塊未正確閉合往往不會破壞底層字符，但會嚴重干擾渲染後的視覺邊界與可讀性。在交付前進行雙端比對，是保障技術文檔準確傳達的關鍵環節。

常見書寫誤區與邊界限制

1. 內外層使用相同數量的反引號

若外層與內層均使用三個反引號，解析器在遇到內層代碼示例的結尾時就會立即截斷代碼塊，把剩下的外層閉合符及後續正文暴露在普通段落中。

1. 前後閉合符號不匹配

外層行首以 開啓，行尾卻以 ~~~~ 閉合。CommonMark 要求閉合圍欄必須使用相同類型的字符，否則閉合行會被解析爲代碼塊正文，代碼塊可能繼續到後續有效閉合行或容器結尾；需要結合實際結構檢查。

1. 把顯示問題誤認爲字符編碼異常

代碼塊排版混亂通常源於語法解析邏輯，而非文件本身的 UTF-8 編碼損壞。排查時應優先檢查標記長度與空白字符，而非盲目重構文本。

下一步行動

在向協作方正式交付技術文檔或發佈教程前，建議保留原稿，再按相關基礎教程完成核對。優先在目標環境的真實渲染器中進行預覽，驗證外層嵌套圍欄、代碼高亮以及頁面相對鏈接的顯示狀態，確認無誤後再執行最終歸檔與交付。