给你的 Obsidian 加点标注框

经常写文档的人应该对“标注框”（callouts block）不会感到陌生。

什么是标注框

所谓标注框，就是一种带有小图标、标题、背景色的一小段文本样式，有时候还会提供折叠功能。有点类似 Markdown 中的 > 引言块，但更加醒目。往往用于诸如提示、警告之类的用途，也经常被称为“谏言块”（admonition）。

在 标准 Markdown 规范 和非常流行的 Github 式 Markdown 规范 中，对于“标注框”都没有明确的定义，连 Markdown 扩展语法中也不见踪迹。因此，关于标注框这件事，各家都是采用各自的语法来实现，不同语法之间互不通用。

Obsidian 中的标注框

目前 Obsidian 有两种方式实现标注框。

1. 官方的 Callouts 标准（从 Obsidian 0.14 版本开始可用）。
2. 第三方插件 Obsidian Admonition 的标注框标准（兼容官方标准）。

Obsidian 官方的标注框写法

Obsidian 的官方写法借助了 Markdown 中的引言块写法：> ，在后面加上 [!标注类型] 就可以添加对应种类的标注框了。

具体能用的标注类型也有不少，tip、success、warning、example 这些看文档时常见的类型都做了支持。

> [!info]
> 这是一个标注框
> 它支持 **Markdown 语法**、 [[内部链接|Wikilinks]] 和 [[嵌入文件|embeds]]。

还可以在标题上添加更多文字信息，改掉原来的 Info 字样。

> [!tip] 小技巧
> 这个小技巧的标题不是默认的 “Tip”

还有更复杂一些的嵌套标注框：

> [!question] 标注框可以被嵌套吗？
> > [!success] 当然
> > > [!example] 第三层嵌套

在 > [!标注] 后，添加一个加号（+）或减号（-） 就可以将其设置为折叠标注框，加号是默认展开，减号是默认折叠。

官方的标注框还有一大优势，它能够被官方的 Publish 服务支持。

附：以下是所有支持的标注类型，它们已经有了一套默认的图标和配色，开箱即用。具体的样式可以参考 Obsidian 标注框支持的样式 文档。

Obsidian Admonition 插件的标注框写法

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 插件支持的种类差别不大，支持的别名更丰富。

Obsidian Admonition 插件还提供了一些配置项，它提供了专属的设置界面进行配置，允许你一次性调整是否开启折叠、允许 Markdown 标题（支持 LaTeX）、定制标注框样式、添加复制按钮等。更适合喜欢自定义的用户。

转标注框的 Quicker 动作

很多时候我们已经写完了一段内容，要将其中的一部分转换为带标注框的样式。如果用 Obsidian 自带的样式，就需要逐行添加 > ，再查一查 > [!info] 的语法，似乎有一点麻烦。

所以我做了一个 Quicker 动作，可以将一段文本转换为带标注框的样式。

🔗 获取 Quicker 动作

应该使用哪一种？

我更推荐 Obsidian 官方的标注框写法，样式足够美观，语法足够简洁，有官方的支持，还有“用加减符号来添加折叠功能”的这样的巧思，实在叫人没什么理由拒绝。

Obsidian Admonition 则更适合需要额外定制的用户，在需要定制颜色、图标的情况下是不二之选。

我想开发者应该会更喜欢 Admonition 的“类代码块语法”。因为开发者在使用代码块的时候，本来也需要在代码块标记后添加 python、js 这样的标注来添加语言高亮，Admonition 只是一种特殊的语言标注而已。不需要费额外的力气就能上手这种写法。

而我个人从 Obsidian 的早期版本就开始使用 Admonition，已经在大量笔记中使用、甚至在模板中都添加了这个写法，既然插件已经保证会保持向下兼容性，那么同样建议老用户继续使用 Admonition 插件。