经常写文档的人应该对“标注框”（callouts block）不会感到陌生。
什么是标注框
所谓标注框，就是一种带有小图标、标题、背景色的一小段文本样式，有时候还会提供折叠功能。有点类似 Markdown 中的 > 引言块，但更加醒目。往往用于诸如提示、警告之类的用途，也经常被称为“谏言块”（admonition）。
在 标准 Markdown 规范 和非常流行的 Github 式 Markdown 规范 中，对于“标注框”都没有明确的定义，连 Markdown 扩展语法中也不见踪迹。因此，关于标注框这件事，各家都是采用各自的语法来实现，不同语法之间互不通用。
Obsidian 中的标注框
目前 Obsidian 有两种方式实现标注框。
- 官方的 Callouts 标准（从 Obsidian 0.14 版本开始可用）。
- 第三方插件 Obsidian Admonition 的标注框标准（兼容官方标准）。
Obsidian 官方的标注框写法
Obsidian 的官方写法借助了 Markdown 中的引言块写法：> ，在后面加上 [!标注类型] 就可以添加对应种类的标注框了。
具体能用的标注类型也有不少，tip、success、warning、example 这些看文档时常见的类型都做了支持。
> [!info]
> 这是一个标注框
> 它支持 **Markdown 语法**、 [[内部链接|Wikilinks]] 和 [[嵌入文件|embeds]]。
还可以在标题上添加更多文字信息，改掉原来的 Info 字样。
> [!tip] 小技巧
> 这个小技巧的标题不是默认的 “Tip”
还有更复杂一些的嵌套标注框：
> [!question] 标注框可以被嵌套吗？
> > [!success] 当然
> > > [!example] 第三层嵌套
在 > [!标注] 后，添加一个加号（+）或减号（-） 就可以将其设置为折叠标注框，加号是默认展开，减号是默认折叠。
官方的标注框还有一大优势，它能够被官方的 Publish 服务支持。
附：以下是所有支持的标注类型，它们已经有了一套默认的图标和配色，开箱即用。具体的样式可以参考 Obsidian 标注框支持的样式 文档。
| 标注类型 | 别名 |
|---|---|
| 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 |
Obsidian Admonition 插件的标注框写法
Obsidian Admonition 插件要比官方功能更早推出，在它的历史版本中一共有三套标注框语法。分别是沿用至今的代码块语法、实验性质的非代码块语法（已移除）、微软文档语法（已移除）。
在官方功能推出后，它对官方的标注框做了增强支持，允许开启“始终启用折叠”之类的选项。并且保证“现有的所有标注框永久有效”，所以你仍然可以了解一下它的写法，并在笔记中继续使用。
最简单的用法就是在代码块后添加一个 ad-标注类别 的标注。
```ad-tip
标注框正文内容
```
接下来是完整的用法，能够自定义标题、折叠功能、图标和颜色。注意顺序不要写错。
```ad-<type> # 标注框类型
title: # 自定义标题
collapse: # 启用折叠功能，输入 `open` 或者 `close`
icon: # 自定义图标，支持 FontAwesome 和 RPGAwesome
color: # 自定义颜色，支持 `200, 200, 200` 的 RGB 颜色写法
标注框正文内容
```
嵌套的用法就更直接了，通过往外层添加更多的代码框符号就可以了，这本身也是代码框的标准写法。
`````ad-question
title: 标注框可以被嵌套吗？
collapse: open
````ad-success
title: 当然
```ad-example
title: 第三层嵌套
collapse: close
```
````
`````
由于借用了代码块的写法，所以相比官方写法还有一个额外的问题，如果想在标注框中再套一层代码块应该怎么写？
答案是用 ~~~ 或者 Tab 缩进来解决，Tab 时没有办法再附加代码高亮效果。
```ad-example
用 ~~~ 包含一些代码
~~~python
def code:
print('some code')
~~~
```
```ad-example
用 Tab 包含一些代码
def code:
print('some code')
```
Obsidian Admonition 可以有限地支持官方的 Publish 服务，具体实现方法是在通过私有域名部署 Obsidian Publish 的时候，添加一部分 JS 代码来实现的。相比直接用官方写法，终归是麻烦了一点。
Obsidian Admonition 插件支持的种类差别不大，支持的别名更丰富。
| 标注类型 | 别名 |
|---|---|
| note | note, seealso |
| abstract | abstract, summary, tldr |
| info | info, todo |
| tip | tip, hint, important |
| success | success, check, done |
| question | question, help, faq |
| warning | warning, caution, attention |
| failure | failure, fail, missing |
| danger | danger, error |
| bug | bug |
| example | example |
| quote | quote, cite |
Obsidian Admonition 插件还提供了一些配置项，它提供了专属的设置界面进行配置，允许你一次性调整是否开启折叠、允许 Markdown 标题（支持 LaTeX）、定制标注框样式、添加复制按钮等。更适合喜欢自定义的用户。
转标注框的 Quicker 动作
很多时候我们已经写完了一段内容，要将其中的一部分转换为带标注框的样式。如果用 Obsidian 自带的样式，就需要逐行添加 > ，再查一查 > [!info] 的语法，似乎有一点麻烦。
所以我做了一个 Quicker 动作，可以将一段文本转换为带标注框的样式。
应该使用哪一种？
我更推荐 Obsidian 官方的标注框写法，样式足够美观，语法足够简洁，有官方的支持，还有“用加减符号来添加折叠功能”的这样的巧思，实在叫人没什么理由拒绝。
Obsidian Admonition 则更适合需要额外定制的用户，在需要定制颜色、图标的情况下是不二之选。
我想开发者应该会更喜欢 Admonition 的“类代码块语法”。因为开发者在使用代码块的时候，本来也需要在代码块标记后添加 python、js 这样的标注来添加语言高亮，Admonition 只是一种特殊的语言标注而已。不需要费额外的力气就能上手这种写法。
而我个人从 Obsidian 的早期版本就开始使用 Admonition，已经在大量笔记中使用、甚至在模板中都添加了这个写法，既然插件已经保证会保持向下兼容性，那么同样建议老用户继续使用 Admonition 插件。