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 那样的彩色提示框。

参考来源