Obsidian Callouts 标注块：语法、类型、示例与自定义 CSS 全指南

Obsidian 的 Callouts（标注块/引述块）功能允许您使用基于引用块（Blockquote）的简单语法，在笔记中突出显示、分组或隐藏特定内容。无论您是想吸引对考试要点的注意、创建可折叠的任务列表，还是将作者备注与正文分开，Callouts 都提供了一种在不打断写作思路的前提下视觉化组织信息的灵活方式。

快速解答：如何在 Obsidian 中创建 Callout？

很简单。Obsidian Callouts 是首行包含 > [!type] 的样式化引用块。本指南为您提供语法说明、即拿即用的示例、内置类型、折叠与嵌套规则，以及常见自定义 CSS 问题的排查方法。您可以参阅 Callouts 官方参考文档 核对最新的类型列表和编辑器命令。

创建 Callout 的核心语法如下：

> [!note] 这是一个 Callout 标注块。

• 在引用块的第一行使用 > [!type]

• 将 note 替换为其他类型，如 tip、warning 或 question

• 按 Enter 回车并继续输入 > 以添加多行文本内容

• 在实时预览（Live Preview）模式下，打开命令面板并选择 Insert callout 即可立即插入默认的 Callout 块。您也可以选中现有文本并运行该命令将其包裹在 Callout 中。

什么是 Obsidian Callouts？

Callouts 是经过样式化处理的引用块，Obsidian 在渲染时会赋予其色彩、图标以及可选的折叠行为。它们于 2022 年年中引入，现已成为视觉化组织笔记的核心功能。

当 Obsidian 遇到以 [!type] 开头的引用块时，会对其进行特殊解析，并展示为一个醒目的 Callout 标注框而非普通引用块。在框体内，您可以自由使用标准 Markdown 语法、双向链接（Wikilinks）、嵌入组件、任务复选框、代码块和内部链接。

在视觉呈现上，Callout 包含一条带颜色的侧边栏、一个图标（例如代表提示的灯泡或代表警告的感叹号）、可选的标题栏以及下方的正文内容。

常见应用场景包括：

• 在会议笔记顶部总结核心要点

• 在学习笔记中高亮考试相关考点

• 在读书笔记中添加防剧透折叠框

请注意，Callouts 仅在 Obsidian 内部渲染此视觉样式。在普通 Markdown 阅读器或 GitHub 上，它们会降级显示为普通的嵌套引用块——内容依然完全可读，只是缺少特殊样式。

Callout 语法与配置详解

本节涵盖所有语法要素：类型、标题、折叠以及正文内容。

基本结构如下：

> [!note] 标题文本
> 正文内容写在这里
> - 也支持列表无序项

第一行包含三个部分：

• 方括号内的类型标识符：[!note]、[!warning]、[!tip]

• 紧跟在类型后面的可选折叠标记：+ 或 -（例如 [!tip]-）

• 类型后面的可选自定义标题文本（例如 [!tip] 考试小贴士）

正文行与普通引用块一样以 > 开头，可以包含无序列表、代码块、图片或任务复选框。

类型关键字区分大小写——对于内置 Callouts，[!NOTE]、[!Note] 和 [!note] 的工作方式完全相同。

修改 Callout 标题

默认情况下，Obsidian 使用类型名称作为标题（例如 “Note” 或 “Warning”）。

要覆盖默认标题：

> [!warning] 部署前请必读此项

对比以下两种写法：

• > [!tip] 显示默认标题 “Tip”

• > [!tip] 更高效的工作流 则替换显示为 “更高效的工作流”

仅包含标题的 Callout 同样有效——只需使用单行如 > [!info] 系统要求，后续无需跟随正文行。

标题中可以包含 Emoji 表情、双向链接以及加粗等格式。

可折叠（Collapsible）Callouts

在类型标识符后直接添加加号或减号，可以控制 Callout 是否支持折叠：

• > [!note]+ 默认处于展开状态

• > [!note]- 默认处于折叠状态

这两个标记都会赋予 Callout 可折叠的能力。符号决定了它初始是打开还是关闭。

可折叠 Callouts 的实用场景包括：

• 在学习笔记中隐藏详细解答过程

• 将长清单折叠在 [!todo]- 标题下

• 在读书笔记中遮挡剧情剧透

在阅读模式和实时预览模式下，用户点击三角图标即可展开或折叠。在源码模式下，折叠标记显示为原始 Markdown。

嵌套 Callouts

您可以通过在父级 Callout 的正文中插入另一个 Callout 块来实现嵌套。

嵌套 Callout 的行在每一级嵌套中都需要额外增加一个 >：

> [!warning] 潜在问题
>> [!tip] 这是替代解决方案

这将创建一个包含嵌套提示框的警告框。另一个示例：包含嵌套 [!example] 解答的 [!question] 问题框。

为了保持笔记的可读性，请限制嵌套深度——通常两级嵌套就已经足够。

Obsidian 支持的内置 Callout 类型

Obsidian 自带多种内置类型，每种类型映射到特定颜色和图标。不支持的自定义类型将自动降级退回 note 的样式。

常见的默认类型及其别名：

• note：通用信息

• abstract / summary / tldr：摘要与总结

• info：补充上下文信息

• todo：待办事项与行动项

• tip / hint / important：建议与核心要点

• success / check / done：已完成事项

• question / help / faq：问题与答疑

• warning / caution / attention：潜在问题与警告

• failure / fail / missing：缺失或失败信息

• danger / error：严重问题与错误

• bug：软件缺陷

• example：代码或概念示例

• quote / cite：高亮引言

不同的社区主题（Themes）可能会重新定义这些类型的样式，因此同一个 [!warning] 在不同主题下外观可能有所不同。

在实时预览模式下，右键点击 Callout 的侧边栏，可以通过右键菜单直接更改其类型，而无需手动修改 Markdown 文本。

未知类型（如 [!idea]）在视觉上会显示为 note 样式，但依然保留对应的 CSS 选择器类名以供自定义样式绑定。

您应该使用哪种 Callout 类型？

类型控制着信息的信号强度，而不仅仅是视觉颜色。建立一套简明的使用约定，以便日后检索笔记时一目了然：

您需要表达的信息信号	推荐的起步类型	实用模式
上下文或定义说明	info 或 abstract	将解释紧挨着其支持的论点放置。
下一步行动	todo	将清单保持在项目或会议上下文附近。
决策或潜在风险	question、warning 或自定义类型	使未解决的争议点保持可见，而不埋没在长篇大论中。
偶尔才需要查看的细节	可折叠的 example 或 note	使用 - 标记保持次要细节默认处于折叠状态。
已完成的结果	success 或 done	专用于阶段性成果，而非每一句积极的陈述。

对于高效的 Obsidian 仓库，一个实用的最小集组合是：用 todo 表示待办，warning 表示阻塞项，question 表示开放性决策，summary 表示复盘笔记。

在仓库中应用 Callout 的实用方法

以下是 Callout 融入真实工作流的方式：

• 学习与备考：使用 [!tip] 标记考试要点，[!question]- 标记附带折叠答案的练习题，在讲座笔记顶部添加 [!summary]

• 软件开发：在破坏性命令周围加上 [!warning]，已知问题标注为 [!bug]，代码片段使用 [!example]

• 项目与任务管理：将清单保存在按里程碑分组的 [!todo]+ 中，完成后转换为 [!success]

• 长文写作：使用 [!note]- 隔离作者备注，在小说草稿中将线索标记为 [!clue]

• 个人知识库：使用 [!info] 记录核心事实，[!quote] 记录引用，[!danger] 记录关键警告

您可以结合预制的 Obsidian 模板示例。对于会议工作流，请参阅 Obsidian 会议模板指南。

用于任务与清单的 Callouts

Callout 内部的任务复选框行为与普通 Obsidian 任务完全一致，并能被全局任务搜索检索到。

[!todo] Callouts 可以将相关复选框聚合在一起：

> [!todo]+ 发布 1.2 版本检查清单
> - [ ] 更新 2025-04-01 发布的 CHANGELOG
> - [ ] 运行回归测试

将类型从 todo 修改为 success 可以直观地传达整个任务块的完成状态。

发布与导出工作流中的 Callouts

Callouts 本质上是面向内部编辑的标注工具，通常不应出现在最终导出的书籍、PDF 或博客文章中。

像 Longform 这样的插件允许添加预处理步骤，在编译前剥离 Callout 标记。脚本可以扫描以 > [! 开头的行并移除包裹结构，同时选择保留或丢弃正文。

使用 CSS 自定义 Callout 样式

Obsidian 通过 data-callout 属性暴露 Callouts，允许您使用自定义 CSS 定义全新的 Callout 类型。

基本步骤：

1. 选择一个自定义类型标识符（如 idea）

2. 在笔记中使用：> [!idea] 新产品构想

3. 在 CSS 中，通过 .callout[data-callout="idea"] 绑定独有的颜色和图标。

Obsidian 默认使用 Lucide 图标集。官方 CSS API 使用 --callout-color 和 --callout-icon 变量；Callout CSS 变量开发者参考 列出了所有可用变量。

实用自定义 Callout 示例

具体的自定义类型构想：

• [!clue]：供小说作者跨章节追踪悬疑线索

• [!risk]：在工程文档中标示技术或业务风险

• [!meeting]：在带日期的会议笔记顶部展示行动摘要

• [!definition]：在知识库中标准化术语条目

将这些 CSS 代码片段添加保存到仓库的 .obsidian/snippets 文件夹中。

排查 CSS 不生效的问题

请按顺序检查：

1. 将 CSS 文件放置在仓库的 .obsidian/snippets 文件夹中，在 设置 → 外观 → CSS 代码片段 中启用它，并重新加载代码片段。
2. 确保笔记中的类型与选择器完全匹配。例如 [!decision] 对应 .callout[data-callout="decision"]。
3. 在两处均将自定义类型名称保持为小写。 内置标识符不区分大小写，但一份 Obsidian 论坛故障排查报告 表明，大小写不匹配会导致自定义选择器无法匹配。
4. 使用您当前 Obsidian 版本内置支持的图标。

搜索、管理与导出 Callouts

使用形如 "[!todo]" 的查询搜索所有待办 Callout。结合路径过滤器：path:"Drafts" "[!clue]" 快速定位线索。

局限性与兼容性说明

Callouts 不属于标准 CommonMark 规范的一部分。在 Typora 或 GitHub 等编辑器中，它们会降级显示为普通嵌套引用块。

部分移动端 Markdown 应用可能会将其显示为纯文本——内容依然清晰可读，但没有颜色或图标样式。

过度使用嵌套和可折叠 Callout 可能会降低较旧移动设备上的渲染性能。

请定期测试导出文件（PDF、DOCX、HTML），以验证 Callout 内部的关键内容是否正确显示。建议在仓库中维护一份样式指南文档，以便协作人员遵循相同的规范。

常见语法错误

折叠标记必须紧贴类型标识符：

> [!faq]- 默认折叠
> 此内容初始状态为隐藏。

> [!faq] - 默认折叠 在连字符前有一个空格，因此这不是规范的折叠语法。如果折叠仍未生效，请检查笔记是否处于阅读视图或实时预览模式，并将代码块与官方示例进行对比。2024 年 Obsidian 论坛报告 指出该额外空格是导致 Callout 无法折叠的原因。

Callouts 是 Obsidian 的扩展功能，而非标准 CommonMark 的一部分。如果 Callout 在其他 Markdown 编辑器中显示为普通引用块，这是正常现象；内容依然可读，但 Obsidian 的样式和折叠行为不会保留。

结语

Obsidian Callouts 是增强型的引用块，可让您在不打断笔记流畅度的前提下高亮、分组和隐藏信息。

核心要点：

• 掌握基础语法：> [!type] 标题

• 挑选一小组契合您工作流的 Callout 类型

• 仅在能切实优化流程的地方添加自定义 CSS

如果您希望从一开始就将日记、项目、复盘和会议模板无缝连接，Obsibrain 提供了开箱即用的 Obsidian 本地优先系统。