Markdown Alert 警告框語法教學

什麼是 Markdown Alert

寫文件的時候，有些內容需要特別醒目——比如「這個操作不可逆」、「建議用命令列方式」這類提示資訊。普通段落很容易被讀者一掃而過，但如果用一個帶顏色和圖示的框把它包起來，就不一樣了。

這就是 Markdown Alert（也叫提示框、警告框、callout）的作用。

不過這裡有個容易混淆的點：原生 Markdown 規範裡並沒有 Alert 這個語法元素。它本質上是 GitHub 在 blockquote（引用塊）基礎上做的一個擴充套件。所以目前這套語法主要在 GitHub 平台上有效——包括 README、Issue、PR 描述、Discussion 等地方。其他平台（比如 GitLab、Obsidian）有的支援，有的不支援，後面會詳細說。

GitHub Alert 語法詳解

GitHub 在 2023 年底正式上線了這套 Alert 語法，總共支援五種類型：

類型關鍵詞用途顏色
NOTE[!NOTE]提示讀者需要關注的資訊藍色
TIP[!TIP]給出有幫助的建議綠色
IMPORTANT[!IMPORTANT]標註關鍵必讀內容紫色
WARNING[!WARNING]警告需要注意的風險橙色
CAUTION[!CAUTION]提示可能產生的負面後果紅色

基本寫法

語法格式很簡單——先寫一個引用符號 >，然後緊跟 [!類型]，下一行再用 > 開頭寫內容：

> [!NOTE]
> 這是一條提示資訊，用來提醒讀者注意某個要點。

渲染出來就是一個藍色背景帶藍色圖示的提示框。每種類型的寫法都是同樣的結構，只是換一下方括號裡的關鍵詞：

> [!TIP]
> 試試用快捷鍵 Ctrl+Shift+V 貼上，可以保留原始格式。
> [!WARNING]
> 刪除操作不可恢復，請確認後再執行。
> [!IMPORTANT]
> 升級前務必備份資料庫。
> [!CAUTION]
> 直接修改生產環境配置可能導致服務中斷。

說實話，語法本身真的沒幾行，但用對了地方效果很好。

多行內容

如果提示框裡有多行文字，每一行都要以 > 開頭：

> [!WARNING]
> 這個操作會導致以下影響：
> 1. 現有快取全部失效
> 2. 使用者需要重新登入
> 3. 部分歷史資料可能遺失

我之前幫一個專案寫遷移文件的時候，就因為這個多行格式踩過坑——中間有一行忘了加 >，結果那段文字就跑到提示框外面去了，閱讀體驗很差。所以寫多行內容的時候，記得檢查每一行。

在 Alert 中使用 Markdown 格式

Alert 裡面不只能寫純文字，普通的 Markdown 格式都能用：

> [!TIP]
> 推薦使用 `git rebase -i` 來整理提交歷史，特別是當你有多個 **WIP** 提交時。
> 具體操作參考 [Git 官方文件](https://git-scm.com/docs/git-rebase)。

粗體、程式碼、連結這些都沒問題。不過要注意，列表在 Alert 裡面的縮排有時候會不太穩定，建議盡量保持簡潔。

自訂標題（可選）

在部分支援 GitHub Alert 的平台上，你可以在類型關鍵詞後面加一段自訂標題：

> [!NOTE] 關於版本相容性
> 目前版本僅支援 Node.js 18 及以上。

不過這個自訂標題功能不是所有地方都支援。GitHub 官方目前主要支援五種標準類型的預設標題，自訂標題的表現可能因平台而異。如果你發現自訂標題沒有生效，就用預設的就行。

五種類型什麼時候用

很多人寫 Alert 的時候不太區分類型，什麼都用 NOTE。其實每種類型有其語意和使用場景：

NOTE（提示）——適用於補充說明、背景資訊這類「知道了更好」的內容。比如告訴讀者某個功能的限制條件，或者解釋一個設計決策的原因。

TIP（建議）——適用於可選的最佳化建議、更高效的操作方式。比如推薦一個快捷操作、一個更好的工具配置。它不是必須遵守的規則，而是「如果你這樣做會更好」。

IMPORTANT（重要）——適用於必須知道的規則或前提條件。和 NOTE 的區別是：IMPORTANT 的內容如果不看，後面的操作可能會出問題。比如「必須先安裝依賴才能執行」、「僅支援 Python 3.10+」。

WARNING（警告）——適用於可能導致問題但可以規避的操作。比如「刪除分支前確保已合併」、「這個 API 已廢棄，建議遷移」。

CAUTION（危險）——適用於可能導致嚴重後果的操作。這是級別最高的提示，用於「做了就回不了頭」的場景。比如「直接操作生產資料庫」、「刪除不可恢復的資料」。

我的習慣是：文件裡別濫用 Alert，一個頁面出現 3-5 個就夠了。太多了讀者反而會「視覺疲勞」，都不看了。

新舊語法對比

如果你之前了解過 GitHub 的提示框功能，可能見過另一種寫法：

> **Note**
> 這是一條提示資訊。

這是 2022 年 GitHub Beta 階段推出的舊語法。新語法是：

> [!NOTE]
> 這是一條提示資訊。

兩種語法在 GitHub 上目前都能渲染，但區別很明顯：

對比項舊語法 > **Note**新語法 > [!NOTE]
上線時間2022年5月（Beta）2023年12月（正式）
類型標識粗體文字方括號標記
多行支援需要額外空行直接逐行加 >
相容性僅 GitHubGitHub + 部分其他平台
標題顯示標題和內容可能擠一行格式穩定

我之前把幾個專案從舊語法遷移到新語法的時候，最大的感受是：舊語法對多行內容的處理確實不太穩定。標題和正文偶爾會擠在同一行，需要手動在中間插入一個空引用行 > 來分隔。新語法就沒這個問題。

如果你還在用舊語法，建議趁早換過來。新語法寫起來更簡單，也更不容易出格式問題。

在 Alert 之前人們怎麼做的

在 GitHub 官方 Alert 功能出現之前，社群有不少變通方案。了解這些有助於理解為什麼 Alert 這麼受歡迎。

表格 + Emoji 方案

用單列表格配合 Emoji 來模擬提示框：

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

這個方法在 GitHub 上確實能渲染出一個帶邊框的區域，但它本質上是個表格，不是語意上的「提示」。而且樣式控制很有限，也不能區分不同級別。

HTML 方案

直接在 Markdown 裡嵌入 HTML：

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

這個方法在普通網頁上沒問題，但 GitHub 出於安全考慮會過濾掉大部分 HTML 樣式屬性，所以 style 屬性在 GitHub 上基本不生效。

引用塊 + 粗體

最樸素的方式就是用 blockquote 加粗體文字：

> **Warning:** 刪除操作不可恢復。

這在所有 Markdown 環境都能渲染，但沒有顏色區分，視覺上就是普通引用塊，不夠醒目。

說白了，GitHub Alerts 之所以好用，就是因為它解決了上面這些方案的痛點——既有顏色和圖示區分，語法又簡單，還是官方支援的功能。

相容性：哪些平台能用

這是很多人關心的問題。[!NOTE] 語法目前的情況：

完全支援：

  • GitHub（README、Issue、PR、Discussion、Gist）——原生支援，渲染效果最好

透過外掛/配置支援：

  • Obsidian —— Obsidian 有自己的 callout 語法，> [!NOTE] 格式與 GitHub Alert 相容
  • VS Code 預覽 —— 需要安裝 markdown-it 外掛（如 markdown-it-github-alerts）才能正確渲染
  • 靜態站點 —— Hugo、VitePress、Docusaurus 等可以透過 markdown-it 外掛支援

不確定/不支援：

  • GitLab —— 目前不原生支援，渲染為普通引用塊
  • Bitbucket —— 不支援
  • 普通 Markdown 編輯器（Typora、MacDown 等）—— 看具體編輯器是否實作了這個擴充套件

如果你寫的內容只在 GitHub 上看，那放心用就行。如果你的文件需要跨平台展示，建議在非 GitHub 平台確認一下渲染效果，或者準備一個降級方案（比如普通引用塊作為後備）。

實際使用技巧

寫了一年多 GitHub Alert，我總結了幾個實用習慣：

第一，選擇合適的類型。 之前看到一個專案把所有提示都用 CAUTION（紅色），結果整篇文件看下來讓人心驚膽戰。其實大部分情況 NOTE 和 TIP 就夠了，WARNING 和 CAUTION 留給真正需要警惕的內容。

第二，內容簡潔。 Alert 框裡的文字不宜太長。如果一個提示框需要寫三段話來解釋，那它可能更適合放在正文中。理想狀態下，Alert 裡放一兩句話就夠了。

第三，位置講究。 Alert 放在相關操作的前面，而不是後面。比如「執行刪除命令前請備份」這樣的警告，應該放在刪除命令的前面，讓讀者先看到警告再看到命令。

第四，別巢狀。 Alert 裡面不要再套一個 Alert，渲染出來會很奇怪。如果確實需要分層提示，把重要的放在外面，次要的用普通文字或列表表達。

常見問題

為什麼我寫的 Alert 沒有渲染出樣式？

最常見的三個原因：

  1. [!NOTE] 後面必須換行——類型標記要單獨佔一行，內容從下一行開始
  2. 內容行的 > 前面不要加空格——必須是行首直接寫 >
  3. 不在 GitHub 環境——其他平台可能不支援這個語法

可以自己定義新的類型嗎？

不行。目前 GitHub 只支援 NOTE、TIP、IMPORTANT、WARNING、CAUTION 這五種。如果你寫了 [!INFO] 或 [!DANGER]，它不會被識別為 Alert，只會渲染成普通引用塊。

Alert 裡面可以放程式碼塊嗎？

可以，但建議用行內程式碼（反引號）而不是多行程式碼塊。多行程式碼塊在 Alert 裡面的縮排處理有時候會有問題，特別是在不同編輯器的預覽中表現不一致。

參考來源