Markdown 程式碼塊指南：內聯程式碼、隔離塊和語法突出顯示

程式碼格式化是 Markdown 最強大的功能之一。無論您是記錄函式、顯示終端命令還是編寫教程，Markdown 程式碼語法都可以使程式碼在視覺上清晰、格式正確，並且（在大多數平臺上）語法突出顯示。本指南涵蓋了有關的所有內容 Markdown 程式碼塊.

內聯程式碼

將短片段或單個表示式括在單個反引號中：

Use `console.log()` to print output.
Set the variable with `const x = 42;`.
The file is saved as `README.md`.

內聯程式碼以等寬字型呈現，在視覺上與周圍的文本不同。將其用於：

• 函式和方法名稱： addEventListener()
• 變數名稱： isLoading
• 檔名： package.json
• 命令引數： --verbose
• 短程式碼表達式

如果您的內聯程式碼包含反引號，請使用雙反引號將其包裝：

`` `backtick inside` ``

防護程式碼塊

對於多行程式碼，使用三個反引號 (`) 開啟和關閉塊：

```
This is a code block.
It preserves all whitespace and line breaks.
No formatting is applied inside.
```

縮排、間距和換行符都被準確保留。

語法突出顯示

在左三個反引號後新增語言識別符號以啟用語法突出顯示：

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
```

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("World"));
```

```bash
#!/bin/bash
echo "Hello, World!"
ls -la ~/Documents
```

通用語言識別符號

縮排程式碼塊

較舊的 Markdown 語法對程式碼塊使用 4 空格縮排：

    function oldStyle() {
        return "This is a code block";
    }

這是 CommonMark 相容的，但可讀性較差，並且不支援語言識別符號。請改用圍欄塊（三個反引號）。

從 Word 文件轉換程式碼

Word 中的等寬文本（Courier New、Consolas 等）在您使用時會轉換為內聯程式碼 WordToMD. Multi-line code in Word converts depending on how it was formatted:

• 等寬字型段落 → 可能成為多個內聯程式碼片段
• Word“程式碼”樣式 → 轉換為程式碼塊
• 文字文本塊 → 可能需要手動圍欄

轉換後，檢查程式碼部分並根據需要新增適當的防護：

1. 查詢應該是塊的程式碼
2. 用三個反引號括起來
3. 新增適當的語言識別符號

特定於語言的示例

HTTP 請求

```http
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "name": "Alice",
  "email": "alice@example.com"
}
```

終端命令

```bash
npm install
npm run build
npm run dev
```

差分輸出

```diff
- const oldValue = "hello";
+ const newValue = "world";
  console.log(newValue);
```

YAML 配置

```yaml
server:
  host: localhost
  port: 8080
  debug: true
database:
  url: postgresql://localhost:5432/mydb
```

巢狀程式碼塊（用於文件）

在記錄 Markdown 本身時，使用 4 個反引號來包裝包含 3 個反引號的塊：

````markdown
```python
# This is a code block inside documentation
```
````

平臺支援

行號

標準 Markdown 不支援程式碼塊中的行號。一些平臺和靜態站點生成器通過外掛新增此功能：

• Prism.js （被許多 SSG 使用）— 新增 {numberLines: true} 在程式碼圍欄中
• GitHub — 渲染的 Markdown 中沒有本機行號（使用 GitHub Blame 檢視代替）
• GitBook — 通過程式碼塊設定的行號

從塊複製程式碼

GitHub 和許多平臺自動向程式碼塊新增“複製”按鈕。這是一個渲染增強功能——它不需要 Markdown 中的任何特殊內容。

FAQ

為什麼我的程式碼塊語法沒有突出顯示？ 語言識別符號丟失或拼寫錯誤，或者平臺不支援特定語言。檢查上面的識別符號列表。

如何在程式碼塊內顯示反引號？ 在受防護的程式碼塊內，反引號被視為文字字元。只有三反引號柵欄需要特殊處理。

我的 Word 文件有彩色語法突出顯示的程式碼。WordToMD 會保留顏色嗎？ 否 - Markdown 程式碼塊不保留顏色格式。WordToMD 將文本轉換為程式碼塊；然後 Markdown 渲染器根據語言識別符號應用語法突出顯示。

我可以突出顯示程式碼塊中的特定行嗎？ 標準 Markdown 不支援此功能。一些平臺（例如 Astro 與 Shiki 或 Hugo）支援通過註釋突出顯示行： {1,3-5} 。

相關指南

• Markdown 語法速查表 — 完整參考
• Word 到 API 文件 — 程式碼較多的文件
• Word 到 GitHub Markdown — GitHub 特定的程式碼格式

結論

Markdown 程式碼塊很簡單：內聯程式碼的反引號，帶有語言識別符號的塊的三個反引號。使用轉換 Word 文件後 WordToMD，檢查等寬文本是否已正確包裝在程式碼語法中，並新增語言識別符號以在目標平臺上正確突出顯示語法。