Callout

给段落加上视觉权重——把"这条很重要 / 这是警告 / 这是顿悟"从平铺文字里视觉拎出来，让读者扫页时不会漏掉。

When to use

✅ 你有一段对读者关键的提示——值得让眼睛停下来
✅ 你想标记警告 / 风险 / 容易踩的坑
✅ 你想把洞察 / 顿悟 / 关键观点从论述流里凸显出来
❌ 整段都是 callout——视觉降级，等于没有 callout
❌ 用 callout 做 layout / 美化——这是错位（layout 用 Layout grid）

Basic syntax

Callout 是带类型标记的标准 blockquote，标记写在第一行的 [!TYPE]：

> [!INFO]
> 这是信息提示。
> 多行内容继续用 `>` 前缀。

> [!WARN]
> 这是警告。

> [!ZEN]
> 这是洞察 / 顿悟。Rho 独有的类型，用于"啊哈时刻"。

渲染：左侧带色彩 bar 的高亮块，配类型图标 + 类型名 header，下方是你的内容。

All types

Rho 支持 3 个原生类型 + 5 个 GitHub-flavored alert = 8 种。

Rho 原生（推荐）

Type	颜色	图标	适用
`[!INFO]`	蓝	ℹ️	一般信息 / 提示 / 上下文
`[!WARN]`	橙	⚠️	警告 / 注意 / 容易出错
`[!ZEN]`	绿	🌿	洞察 / 顿悟 / 关键观点

GitHub-flavored alerts（兼容）

Type	颜色	适用
`[!NOTE]`	蓝	信息（同 INFO，GFM 标准）
`[!TIP]`	绿	实用建议
`[!IMPORTANT]`	紫	强调关键点
`[!WARNING]`	黄	警告（同 WARN，GFM 标准）
`[!CAUTION]`	红	严重风险

怎么选 INFO 还是 NOTE？ 一致性优先。如果你的文档主要在 GitHub 渲染，用 GFM 类型（[!NOTE] / [!TIP] 等）—— GitHub web 不认 [!INFO]。如果你的文档主要在 Rho 渲染，用 INFO / WARN / ZEN —— 它们意义更精准（特别是 ZEN，GFM 没有对应物）。

Examples

Example 1：最简单的提示

> [!INFO]
> Rho 的 `.md` 文件可以直接用任何 markdown 编辑器打开。

渲染：蓝色高亮块，左侧蓝条 + ℹ️ 图标 + "INFO" header，下方一段文字。

Example 2：多行 + 内联代码

> [!WARN]
> 不要在 callout 第一行的标记里加空格：
>
> - ✅ 正确：`> [!INFO]`
> - ❌ 错误：`> [! INFO]` 或 `> [ !INFO ]`
>
> 解析器对空格敏感。

渲染：橙色高亮块，多段内容（含列表 + 内联代码）都被同一个 callout 框住。

Example 3：ZEN（Rho 独有）

> [!ZEN]
> Markdown 之所以战胜 wiki / RTF / docx，是因为它有一条不可变的承诺：
> **任何工具都能打开它，最坏情况下看到的是纯文本——而不是渲染失败的白屏**。
>
> Rho 不能违背这条。所有 DSL 必须 plain-text fallback。

渲染：绿色高亮块，🌿 图标 + "ZEN" header。视觉重量比 INFO 重，比 WARN 不那么紧迫——专门给"洞察类"内容留的语义槽。

Example 4：可选 inline 标题

部分 reader 支持在标记后加自定义标题：

> [!WARN] 这条 API 在 v0.7 后会移除
> 请改用新 API `rho.format()`。详见迁移指南。

渲染：header 显示自定义标题"这条 API 在 v0.7 后会移除"，替代默认的"WARN"字样。

注意：自定义标题在标准 GFM 里不是所有 reader 都支持。Rho 支持，GitHub 部分支持，Obsidian 支持。要保证最大兼容性，把标题写进 body 第一行：
> [!WARN]
> **这条 API 在 v0.7 后会移除**
> 请改用 `rho.format()`...

Plain-text fallback behavior

Callout 是纯标准 markdown blockquote + 一个 [!TYPE] 标记。在不支持 callout 的 reader 里，它退化为：

> [!INFO]
> 这是信息提示。
> 多行内容继续用 > 前缀。

→ 显示为带 [!INFO] 标记的普通引用块——读者依然能看到内容、依然能识别 "这是个 INFO" 的语义意图。

具体各 reader 的渲染：

Reader	渲染效果
Rho	完整高亮块（彩色 bar + 图标 + header）
GitHub web	完整高亮块（仅 `[!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]`，Rho 原生类型显示为 `[!INFO]` 字面量 + 普通引用）
Obsidian	完整高亮块（识别广义 callout 类型，含 INFO / WARN 等）
VS Code 默认预览	普通 blockquote + `[!INFO]` 字面量可见
cat / less / 任何文本编辑器	源文件 plain text

所有情况读者都能读懂——这是 plain-text fallback 的设计承诺。

Common pitfalls

1. 标记大小写

> [!info]    ← ⚠️ 部分 reader 不识别小写
> [!INFO]    ← ✅ 推荐（spec 标准）

类型标记应使用大写。Rho 容忍小写，但 GitHub 严格要求大写。

2. 多段中间不要空行

> [!INFO]
> 第一段。

> 第二段。           ← ❌ 中间空行 → 第二段不再属于 callout

正确写法：每段间用一个只含 > 的空引用行：

> [!INFO]
> 第一段。
>
> 第二段。           ← ✅ 仍在同一 callout 里

3. 嵌套 callout 不支持

> [!INFO]
> 外层 INFO
> > [!WARN]         ← ❌ 嵌套不支持，会渲染成普通嵌套引用
> > 内层 WARN

如果你需要"在 INFO 里强调一段"，用粗体 / inline code / 列表，不要嵌 callout。

4. 误把 layout 任务交给 callout

> [!INFO] 功能 A
> 描述 A

> [!INFO] 功能 B
> 描述 B

> [!INFO] 功能 C
> 描述 C

这是 layout 的活，不是 callout 的活。callout 用来强调；并列展示用 Layout grid + cards。

5. 整篇都是 callout

如果一页里 80% 是 callout 块，视觉权重失效。callout 应该稀少而显眼——~~每段强调，等于没强调~~。