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] 和 > 之间没有空格问题不大，但 [!NOTE] 后面必须换行——类型标记要单独占一行，内容从下一行开始
  2. 内容行的 > 前面不要加空格——必须是行首直接写 >
  3. 不在 GitHub 环境——其他平台可能不支持这个语法

可以自己定义新的类型吗？

不行。目前 GitHub 只支持 NOTE、TIP、IMPORTANT、WARNING、CAUTION 这五种。如果你写了 [!INFO] 或 [!DANGER]，它不会被识别为 Alert，只会渲染成普通引用块。

Alert 里面可以放代码块吗？

可以，但建议用行内代码（反引号）而不是多行代码块。多行代码块在 Alert 里面的缩进处理有时候会有问题，特别是在不同编辑器的预览中表现不一致。

参考来源