Markdown 警告框語法教學

什麼是 Markdown 警告框

寫技術文件的時候，總有一些內容需要讀者特別留心——「這個操作不可逆」、「這個 API 已廢棄」、「執行前必須備份資料」。這類資訊如果只是用普通段落寫出來，十有八九會被跳過。但如果用帶顏色和圖示的框把它包起來，效果就完全不一樣了。

這就是 Markdown 警告框（Warning Box）的作用。

不過要說明一下：Markdown 原生規範裡沒有「警告框」這個語法元素。CommonMark 規範只定義了標題、列表、引用塊、程式碼塊這些基礎結構。警告框是各平台在 blockquote（引用塊）基礎上做的擴展，語法和渲染效果因平台而異。

這篇文章會覆蓋所有主流平台的警告框寫法，你直接找自己用的那個平台抄程式碼就行。

GitHub 警告框：[!WARNING] 語法

如果你主要在 GitHub 上寫文件——README、Issue、PR 描述、Discussion——這是最直接的方式。GitHub 在 2023 年 12 月正式上線了 Alert 語法，其中 WARNING 類型就是專門用來顯示警告的。

基本寫法

語法很簡單，在引用塊的第一行寫 > [!WARNING]，後續行用 > 開頭寫內容：

> [!WARNING]
> 刪除操作不可恢復，請在執行前確認。

渲染出來就是一個橙色的提示框，帶有一個警告圖示。整個語法基於 blockquote，所以即使在不支援 Alert 的平台上，內容也不會遺失——只會退化為普通引用塊。

多行內容

警告框裡有多行文字時，每一行都要以 > 開頭：

> [!WARNING]
> 這個版本存在以下已知問題：
> 1. 大檔案上傳可能逾時
> 2. Safari 瀏覽器下樣式錯位
> 3. 匯出功能暫時不可用

我之前幫一個專案寫遷移文件的時候，就因為中間有一行忘了加 >，結果那段文字跑到了警告框外面。讀者回饋說文件格式亂了，排查了半天才發現是這個小問題。所以寫多行警告框的時候，建議寫完檢查一遍每一行的開頭。

在警告框中使用 Markdown 格式

警告框內部支援常見的 Markdown 格式——粗體、行內程式碼、連結都可以用：

> [!WARNING]
> `v2.0` 版本已廢棄 `getUser()` 方法，建議遷移到 `fetchUser()`。
> 詳見 [遷移指南](https://example.com/migration)。

不過要注意清單和程式碼塊在警告框內部的縮排有時候會不太穩定，特別是在不同編輯器的預覽中。如果可能的話，建議保持警告框內容簡潔，複雜的格式放到正文中。

警告框在各平台的寫法對比

GitHub 的 [!WARNING] 不是唯一的寫法。不同平台有自己的語法來建立警告框，下面把主流平台的寫法整理在一起。

GitHub

> [!WARNING]
> 警告內容寫在這裡。

支援 5 種類型：NOTE、TIP、IMPORTANT、WARNING、CAUTION。WARNING 顯示為橙色框。

Obsidian

> [!warning] 自訂標題
> 警告內容寫在這裡。

Obsidian 的 callout 語法跟 GitHub 幾乎一樣，但它支援自訂標題（方括號後面直接寫），還支援 12 種內建類型。另外 Obsidian 支援可摺疊的 callout：

> [!warning]- 點擊展開查看警告
> 這段內容預設摺疊，需要點擊才能看到。

MkDocs（Material 主題）

!!! warning "注意"
    警告內容寫在這裡，必須縮排 4 個空格。

MkDocs 用 !!! 標記，類型名後面可以跟引號包裹的標題。內容必須縮排 4 個空格——這是新手最容易出錯的地方。如果縮排不對，內容不會被識別為警告框的一部分。

Docusaurus

:::warning
警告內容寫在這裡。
:::

Docusaurus 用三個冒號包裹內容，語法最簡潔。自訂標題用方括號：

:::warning[資料遺失風險]
警告內容寫在這裡。
:::

MyST / Jupyter Book

```{warning}
警告內容寫在這裡。

MyST 用類似程式碼區塊的指令語法，支援 `:class: dropdown` 實現可摺疊。

### Quarto

```markdown
::: {.callout-warning title="自訂標題"}
警告內容寫在這裡。
:::

Quarto 用 Pandoc 的圍欄 div 語法，帶 .callout-warning 類別。

寫法對照表

平台語法自訂標題可摺疊不支援時退化
GitHub> [!WARNING]不支援不支援普通引用塊
Obsidian> [!warning]支援支援普通引用塊
MkDocs!!! warning支援支援（???）不渲染
Docusaurus:::warning支援不支援不渲染
MyST```{warning}支援支援不渲染
Quarto::: {.callout-warning}支援支援不渲染

從這張表能看出來，GitHub 和 Obsidian 的語法最接近，都用 blockquote 擴展。好處是同一份 Markdown 在兩個平台之間遷移成本幾乎為零。而且它們在不支援的環境下會退化為普通引用塊，內容不會遺失。

在不支援 [!WARNING] 的環境怎麼辦

如果你用的平台不支援 GitHub Alert 語法（比如 GitLab、Bitbucket，或者普通的 Markdown 編輯器），還有幾種變通方案可以建立類似警告框的效果。

引用塊 + Emoji + 粗體

最通用的方案——在所有 Markdown 環境都能渲染：

> ⚠️ **Warning:** 刪除操作不可恢復，請在執行前確認。

這個寫法沒有顏色框和圖示，視覺上就是普通引用塊。但加上 ⚠️ Emoji 和粗體文字後，醒目程度已經好很多了。如果你需要跨平台相容，這是最安全的選擇。

表格模擬

用單欄表格配合 Emoji 來模擬一個帶邊框的區域：

| ⚠️ **Warning** |
|:---|
| 刪除操作不可恢復 |

這個方法在 GitHub 上能渲染出一個帶邊框的區域。但它本質上是表格，不是語意上的警告框，而且樣式控制很有限——沒法改顏色，也沒辦法區分不同級別。

HTML 方案

直接嵌入 HTML 元素並加入樣式：

<div style="background: #fff3cd; padding: 12px; border-left: 4px solid #ffc107; border-radius: 4px;">
<strong>⚠️ Warning:</strong> 刪除操作不可恢復。
</div>

這個方法在自己控制渲染環境的靜態站點上完全沒問題。但要注意：GitHub 出於安全考慮會過濾掉 style 屬性，所以在 GitHub 的 README、Issue 裡這個方法基本無效——div 會被渲染，但樣式全丟了。

說實話，如果你只是需要在 GitHub 上寫警告框，直接用 [!WARNING] 就好。HTML 方案更適合自建文件站或者部落格。

WARNING 和其他類型的區別

GitHub Alert 提供了 5 種類型，很多人搞不清楚什麼時候該用 WARNING。把它們放在一起對比一下：

類型語意嚴重程度典型場景
NOTE補充資訊低「這個功能有大小限制」
TIP可選建議低「推薦用命令列方式」
IMPORTANT必須知道中「僅支援 Python 3.10+」
WARNING潛在風險中高「這個 API 已廢棄」
CAUTION嚴重後果高「直接操作生產資料庫」

WARNING 和 CAUTION 的區別是最常被問到的。簡單來說：WARNING 是「小心點，可能會出問題」，CAUTION 是「別亂來，出了問題後果嚴重」。

舉個例子——「刪除分支前確保已合併」適合用 WARNING，「直接修改生產資料庫可能導致服務中斷」應該用 CAUTION。

我的習慣是：大部分需要引起注意的內容用 WARNING 就夠了。CAUTION 留給那些「做了就回不了頭」的場景。一個專案文件裡如果到處都是 CAUTION，讀者反而會麻木。

警告框內容怎麼寫

語法本身沒幾行，但警告框裡寫什麼、怎麼寫，才是真正影響效果的部分。

措辭要具體。 「請謹慎操作」這種話說了等於沒說。好的警告應該告訴讀者具體的後果和替代方案：「刪除後資料不可恢復。如需保留資料，請先執行備份（見第 3 步）。」

放在操作前面。 警告應該在讀者看到相關操作之前就出現。如果先寫了 rm -rf /data 再在下面說「注意這個命令會刪除所有資料」，那就晚了。

內容要簡短。 警告框裡放一兩句話最理想。如果需要三段話來解釋風險，那可能更適合放在正文裡，然後在操作步驟前面加一個簡短的警告框做提醒。

別濫用。 一個頁面出現 3-5 個警告框就很多了。太多了讀者會習慣性跳過。

常見問題

為什麼我寫的 [!WARNING] 沒有渲染出樣式？

最常見的原因有三個：

  1. [!WARNING] 必須單獨佔一行 — 類型標記後面的內容要從下一行開始
  2. 內容行的 > 要在行首 — > 前面不要加空格
  3. 不在 GitHub 環境 — GitLab、Bitbucket 等平台不原生支援這個語法

可以自訂 WARNING 的顏色和圖示嗎？

在 GitHub 上不行。五種 Alert 類型的顏色和圖示都是固定的。如果你需要自訂外觀，得用 Obsidian（透過 CSS 自訂 callout）或者 MkDocs（透過 CSS 覆蓋 admonition 樣式）。

WARNING 框裡面可以巢狀另一個框嗎？

不建議。GitHub Alert 不支援巢狀。在 Obsidian 和 MkDocs 中技術上可以巢狀，但巢狀超過兩層閱讀體驗就很差了。

GitLab 上怎麼寫警告框？

GitLab 目前不原生支援 [!WARNING] 語法。你可以用引用塊加 Emoji 的變通方案：> ⚠️ **Warning:** 警告內容。GitLab 也有自己的 Markdown 擴展，但沒有像 GitHub 那樣的彩色提示框。

參考來源