标注块

标注是一种极好的方法，可以引起对某些概念的额外注意，或更清楚地表明某些内容是补充性的或只适用于某些情况。

Callout Types|标注类型

有五种不同类型的标注可供选择。

  • note
  • warning
  • important
  • tip
  • caution

根据您选择的类型，颜色和图标会有所不同。以下是各种类型在 HTML 输出中的样子：

注解

请注意，有五种类型的标注，包括 note注解, tip提示, warning警告, caution注意, and important重要.

警示

标示提供了一种简单的方法来吸引人们的注意，例如对这一警告的注意。

This is Important

危险，标注将真正提高你的写作水平。

Tip With Title

一个带标题的标注示例。

这是一个用户可以展开的 “折叠式”警句呼出示例。您可以使用 collapse="true" 将其默认折叠，或使用 collapse="false" 制作默认展开的可折叠呼出。

此功能还不适用于 Revealjs 演示（参见问题 1328）。

Markdown Syntax|Markdown语法

使用以下语法在标记符中创建标注（注意，标注中使用的第一个标记符标题将作为标注标题）：

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::

::: {.callout-tip}
## Tip with Title

这是一个带有标题的标注示例。
:::

::: {.callout-caution collapse="true"}
## 展开了解折叠|Expand To Learn About Collapse

这是一个可由用户展开的 "折叠式 "警句呼出示例。您可以使用 `collapse="true"` 将其默认折叠，或使用 `collapse="false"` 制作默认展开的可折叠提示。
:::

请注意，上述标注标题是通过在标注顶部使用标题来定义的。如果您愿意，也可以使用 title 属性指定标题。例如：

::: {.callout-tip title="Tip with Title"}
这是一个带有标题的标注示例。
:::

Customizing Appearance|自定义外观

Collapse|折叠

通过在标注上设置 collapse属性，可以创建用户可以展开的 folded 。如果设置 collapse=true，标注将可展开，但默认情况下是折叠的。如果设置 collapse=false，则标注可展开，但默认为展开。

Appearance|外观

Callouts have 3 different looks you can use.

default 默认外观为彩色标题和图标。
simple 外观重量较轻，不包含彩色标题背景。
minimal 最小化处理，为标注应用边框，但不包括标题背景色或图标。

可以在文档（或项目 yaml）中全局设置标注外观：

callout-appearance: simple

或在标注上设置 appearance 属性。例如:

::: {.callout-note appearance="simple"}

## Pay Attention|注意

使用标注是一种有效的方法，可以突出读者特别考虑或关注的内容。

:::

其显示为:

Pay Attention

使用标注是一种有效的方法，可以突出读者特别考虑或关注的内容。

Icons|图标

除了控制标注的外观外，您还可以在文档（或项目）yaml 中设置全局选项，选择直接控制;图标：

callout-icon: false

或直接在标注上设置属性：

::: {.callout-note icon=false}

## Pay Attention|注意

使用标注是一种有效的方法，可以突出读者特别考虑或关注的内容。

:::

Which will appear as:

Pay Attention|注意

使用标注是一种有效的方法，可以突出读者特别考虑或关注的内容。

Format Support|支持格式

下列格式可呈现如上图所示的标注：

  • HTML
  • PDF
  • MS Word
  • EPUB
  • Revealjs (without collapse option)

请注意，如果禁用标准 HTML 主题（例如指定 theme: none 选项），HTML 的标注渲染将不可用。此外，有些功能是使用 Bootstrap 的文档所特有的，比如可折叠的标注，在其他文档中就无法使用。

当目标格式不支持标注时，它们会被呈现为简单的带粗体标题的楷体引号。

Cross-References|交叉引用

要交叉引用提示，请添加一个以相应提示前缀开头的 ID 属性（请参阅 表 1）。然后就可以使用通常的 @语法引用调用。例如，在这里我们将 ID #tip-example 添加到提示中，然后再引用它：

::: {#tip-example .callout-tip}
## 交叉引用提示

添加以 `#tip-` 开头的 ID 以引用 `tip`。
:::

See @tip-example...

渲染如下：

Tip 1: 交叉引用提示

添加以 #tip- 开头的 ID 以引用 tip。

See Tip 1…

添加以 #tip- 开头的以ID引用 tip。

表 1: 提示交叉引用的前缀
Callout Type Prefix
note #nte-
tip #tip-
warning #wrn-
important #imp-
caution #cau-

目前只有 HTML、PDF 和 MS Word 支持交叉引用标注。