如何在 Markdown 寫程式碼區塊：用三個反引號圍起來。

圍欄式程式碼區塊

圍欄是至少三個反引號組成的一行，區塊以同樣長度（或更長）的一行結束。兩者之間的內容都會照打字的樣子顯示：沒有粗體、沒有連結，也不會把行接在一起。

```
plain text, no colors
  indentation is kept
```

也可以改用三個波浪號：~~~ 開始，~~~ 結束。兩種不能混用，所以用波浪號開頭的區塊必須用波浪號結尾。把每一行縮排四個空格也能做出程式碼區塊，這是較舊的寫法，但無法指定語言名稱，所以圍欄是更好的選擇。

語言標籤與語法醒目提示

開頭圍欄之後的那個字是資訊字串（info string）。多數應用程式用它來挑選醒目提示器：

```json
{ "name": "dotmd", "private": true }
```

在 GitHub、DotMD 與多數應用程式都適用的常見名稱：

• js 或 javascript、ts 或 typescript、python、swift、go、rust
• bash、sh 或 zsh，用於 shell 指令
• json, yaml, html, css, sql
• markdown 或 md 用來顯示 Markdown 本身，diff 用於變更，text 表示不上色

可用名稱的完整清單取決於應用程式與它的醒目提示器。應用程式不認得的名稱不算錯誤：區塊只是不上色顯示。沒有指定語言的區塊也會以純文字顯示。

在程式碼區塊中顯示反引號

如果程式碼中有一行是三個反引號，就用更多的反引號做圍欄。結尾圍欄必須至少和開頭一樣長，所以要顯示三個就用四個：

````markdown
```swift
let x = 1
```
````

本頁就是這樣顯示含有程式碼區塊的 Markdown 範例。波浪號圍欄的做法相同：以 ~~~~ 開啟的區塊可以包含 ~~~。

行內程式碼

句子中的指令或名稱，用單個反引號包起來：`npm install` 會顯示為 npm install。要顯示反引號本身，就把整段放在兩個反引號之間；如果程式碼以反引號開頭或結尾，則在裡面加一個空格：

``a `tick` inside``

行內程式碼也能避免 * 和 _ 這類字元被當成格式，因此很適合用來寫檔名與變數。

清單與引用中的程式碼

圍欄式區塊可以放在清單項目中。把圍欄縮排到與項目文字對齊，它才會繼續屬於該項目：

1. Install the tool:

   ```bash
   brew install example
   ```

2. Run it.

圍欄前要留一個空行，並讓程式碼的每一行縮排相同的量。在引用區塊中，圍欄的每一行都要以 > 開頭。

diff 區塊

把區塊標記為 diff，在會對 diff 醒目提示的應用程式（包括 GitHub）中，以 + 或 - 開頭的行會顯示綠色與紅色：

```diff
- let timeout = 30
+ let timeout = 60
```

這是在文件、README 或規格中呈現變更的便利方式，不需要截圖。

常見錯誤

• 結尾圍欄比開頭短，區塊就永遠不會結束，把頁面其餘部分都吞掉。
• 在嚴格的應用程式中，語言標籤前有空格。如果沒出現顏色，請寫 ```js，不要寫 ``` js。
• 在同一個區塊中混用反引號與波浪號。
• 在某些應用程式中，清單項目或段落之後的圍欄前沒有空行。請加上一行。
• 彎引號。從文書處理軟體貼上的文字，可能把程式碼中的直引號變成彎引號。請以純文字貼上。

有些圍欄不是用來顯示程式碼的。標記為 mermaid 的區塊，只要語法有效，GitHub 與 DotMD 都會把它繪製成圖表。

檢查顏色

測試語言標籤最快的方式，是在閱讀器中開啟檔案。DotMD 以 highlight.js 為圍欄區塊上色，淺色與深色外觀都支援，游標移到區塊上時還會出現 Copy 按鈕。閱讀免費，其餘語法則整理在 Markdown 速查表的一頁中。

關於 Markdown 程式碼區塊的常見問題

更多問題