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 上也不会被识别。

参考来源