Markdown Callout 提示框語法教學

Markdown 本身沒有原生的 callout（提示框）語法。這個功能屬於各平台的擴展實作——每個編輯器或文件工具都搞了一套自己的寫法。好消息是，大部分平台的語法都不複雜，而且有個共同點：本質上都是對 blockquote（引用塊）的增強。

這篇文章把主流平台的 callout 寫法整理清楚，你直接對照自己的工具抄程式碼就行。

先搞清楚：Callout 是什麼？

Callout 就是在文件裡插入一個帶顏色、帶圖示的提示框，用來引起讀者注意。常見的類型有：

類型用途
Note（備註）補充說明、旁註
Tip（技巧）實用建議、快捷方式
Warning（警告）需要注意的風險
Important（重要）必須注意的關鍵資訊
Caution（危險）可能導致資料遺失或錯誤的操作
Info（資訊）一般性資訊提示
Example（範例）程式碼或用法範例

不同平台支援的類型數量不一樣，但核心就這幾個。先理解用途，語法反而好記。

GitHub Alerts：最簡單的入門寫法

如果你主要在 GitHub 上寫 README、Issue 或 PR 描述，用 GitHub Alerts 就夠了。語法基於 blockquote，在引用行開頭加 [!TYPE] 標記：

> [!NOTE]
> 這是一條備註資訊。

> [!TIP]
> 這是一個實用技巧。

> [!WARNING]
> 這是一個警告提示。

> [!IMPORTANT]
> 這是一條重要資訊。

> [!CAUTION]
> 這表示危險操作，請謹慎。

GitHub 支援 5 種類型：NOTE、TIP、WARNING、IMPORTANT、CAUTION。類型關鍵字不區分大小寫，寫 [!note] 和 [!NOTE] 效果一樣。

有一點值得注意：如果你的 Markdown 渲染器不支援 GitHub alerts 語法，這些內容會退化為普通 blockquote，不會顯示特殊樣式，但文字內容不會遺失。這是 blockquote 基礎語法的兜底機制——Markdown 的設計哲學就是優雅降級。

說實話，我在好幾個專案裡都用 GitHub alerts 寫 README，簡單好記。但有一次在巢狀清單裡用 > [!NOTE]，發現渲染效果不太理想——巢狀層級深的時候，樣式會有些錯位。建議在扁平的段落之間使用，別巢狀太深。

Obsidian Callout：類型最豐富的寫法

Obsidian 的 callout 語法和 GitHub Alerts 幾乎一樣，也是用 blockquote 加 [!TYPE]，但支援的類型多得多：

> [!note]
> 這是一條備註。

> [!info] 自訂標題
> 這條 callout 帶自訂標題。

> [!warning]
> 這是一個警告。

> [!tip]
> 這是一個技巧提示。

> [!example]
> 這是一個範例。

> [!quote]
> 這是一條引用。

Obsidian 支援 12 種內建類型：note、abstract、info、todo、tip、success、question、warning、failure、danger、bug、example、quote。每種都有預設的顏色和圖示。

可摺疊 Callout

Obsidian 支援讓 callout 可摺疊，加個 + 或 - 就行：

> [!note]+ 點擊展開（預設展開）
> 這條內容預設展開，可以摺疊。

> [!note]- 點擊展開（預設摺疊）
> 這條內容預設摺疊，需要點擊才能看到。

+ 表示預設展開可摺疊，- 表示預設摺疊。這個功能在寫長文件時特別好用，把補充說明摺疊起來，保持頁面整潔。

巢狀 Callout

Obsidian 允許 callout 互相巢狀：

> [!note]
> 外層備註
> > [!tip]
> > 內層技巧

不過說實話，巢狀超過兩層就很難閱讀了，建議最多巢狀一層。

自訂 Callout 類型

Obsidian 支援透過 CSS 建立自訂 callout 類型。在 CSS snippet 裡加：

.callout[data-callout="my-custom"] {
    --callout-color: 255, 100, 50;
    --callout-icon: lucide:flame;
}

然後在 Markdown 裡就能用了：

> [!my-custom] 自訂提示
> 這是自訂類型的 callout。

我之前給一個專案做文件站點時踩了個坑：自訂 callout 的 data-callout 值必須和 Markdown 裡的 [!type] 完全一致，包括大小寫。當時寫了個 [!My-Custom] 但 CSS 裡用了 my-custom，怎麼都不生效，排查了半天才發現是大小寫不符。

MkDocs Material Admonition：文件站點的標準方案

MkDocs 搭配 Material 主題是寫技術文件的熱門選擇，它的 admonition 用 !!! 標記：

!!! note
    這是一條備註。

!!! warning "自訂標題"
    這是一條帶自訂標題的警告。

!!! tip ""
    這條 callout 沒有標題，只顯示圖示和內容。

語法有幾個細節：

  • !!! 後面跟類型名（如 note、warning）
  • 類型名後可以用引號指定標題
  • 內容必須縮排 4 個空格（這是新手最容易出錯的地方）
  • 空字串標題 "" 會隱藏標題文字

可摺疊 Admonition

把 !!! 換成 ??? 就能實現可摺疊效果：

??? tip "點擊展開"
    這條 admonition 預設摺疊。

???+ warning "預設展開"
    這條 admonition 預設展開，但可以摺疊。

??? 預設摺疊，???+ 預設展開可摺疊。需要在 mkdocs.yml 中啟用 pymdownx.details 擴展。

設定方法

在 mkdocs.yml 中加入：

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Docusaurus Admonition：三冒號語法

Docusaurus 用三個冒號 ::: 包裹內容：

:::note
這是一條備註。
:::

:::tip[自訂標題]
這是一個技巧提示。
:::

:::warning
這是一個警告。
:::

:::danger
這是一個危險提示。
:::

Docusaurus 支援 5 種類型：note、tip、info、warning、danger。自訂標題用方括號 [標題] 而不是引號——這個細節跟其他平台不一樣，別搞混了。

也可以同時用 ::: 和 :::tip 作為開始和結束標記：

:::note[我的標題]
這是內容段落。

可以包含多行內容。
:::

MyST Markdown / Jupyter Book：指令式語法

MyST Markdown 用類似程式碼區塊的指令語法：

```{note}
這是一條備註。
這是一個警告。
這是一條帶自訂標題的提示。

也支援可摺疊：

````markdown
```{note} 可摺疊備註
:class: dropdown
這條內容預設摺疊。

MyST 主要用在 Jupyter Book 和學術文件場景。如果你在寫科研筆記或技術書籍，這可能是你會遇到的語法。

## Quarto / Pandoc：圍欄式 Div

Quarto（基於 Pandoc）用帶有 `.callout-*` 類別的圍欄 div：

```markdown
::: {.callout-note}
這是一條備註。
:::

::: {.callout-tip}
這是一個技巧提示。
:::

::: {.callout-warning title="自訂標題"}
這是一個帶標題的警告。
:::

Quarto 支援 5 種類型：note、tip、warning、important、caution。語法稍顯囉嗦，但和 Pandoc 的圍欄 div 體系一致。

全平台相容性對照

一張表看清各平台差異：

特性GitHubObsidianMkDocsDocusaurusMySTQuarto
語法> [!TYPE]> [!TYPE]!!! type:::type```{type}::: {.callout-type}
內建類型數512+自訂5自訂5
自訂標題不支援支援支援支援支援支援
可摺疊不支援支援支援不支援支援支援
巢狀有限支援支援支援支援支援
自訂類型不支援CSS 自訂CSS 自訂JSX 自訂不支援不支援
不支援時退化普通 blockquote普通 blockquote不渲染不渲染不渲染不渲染

從表裡可以看出，GitHub 和 Obsidian 的語法最接近，都用 blockquote 擴展。這意味著同一份 Markdown 在兩個平台之間遷移成本最低。

該用哪種語法？

選語法取決於你的使用場景：

  • 只寫 GitHub README → GitHub Alerts，夠用了
  • 用 Obsidian 記筆記 → Obsidian Callout，類型豐富，支援摺疊和巢狀
  • 搭技術文件站（MkDocs） → MkDocs Admonition，搭配 Material 主題效果最好
  • 搭文件站（Docusaurus） → Docusaurus Admonition，三冒號語法簡單直接
  • 學術文件（Jupyter Book） → MyST 指令語法
  • 資料科學報告（Quarto） → Quarto Callout

如果你寫的內容需要在多個平台之間共享，我的建議是統一用 GitHub Alerts 語法（> [!TYPE]）。它在 GitHub 和 Obsidian 上都能正常渲染，在其他平台上至少會退化成普通 blockquote，內容不會丟。

常見問題

Markdown 標準支援 callout 嗎？

不支援。CommonMark 規範裡沒有 callout 的定義。所有 callout 功能都是各平台的擴展實作，語法互不通用。

GitHub Alerts 可以自訂顏色和圖示嗎？

不行。GitHub 只支援 5 種預設類型，顏色和圖示都是固定的，不能自訂。

Obsidian 的 callout 類型可以自己加嗎？

可以。透過 CSS snippet 定義 callout[data-callout="類型名"] 就能建立自訂類型，自訂顏色和圖示。

MkDocs 的 admonition 內容為什麼要縮排 4 個空格？

這是 Python-Markdown 的 block 插件語法要求。!!! 後面的內容必須在同一縮排層級，4 個空格是標準縮排。如果縮排不對，內容可能不會被識別為 admonition 的一部分。

不同平台的 callout 語法能混用嗎？

不能。每種語法只在自己的平台上生效。如果你把 :::note 寫在 Obsidian 裡，它只會被當成普通文字。同樣，!!! note 在 GitHub 上也不會被識別。

參考來源