标注块

标注块是吸引额外注意某些概念，或更明确地指示某些内容是补充性的或仅适用于某些场景的绝佳方式。

标注类型

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

  • note
  • warning
  • important
  • tip
  • caution

根据你选择的类型，颜色和图标会有所不同。以下是不同类型在HTML输出中的外观：

Note

请注意，有五种类型的标注块，包括：note、tip、warning、caution 和 important。

Warning

标注块提供了一种简单的方式来吸引注意力，例如，这个警告。

这很重要

危险，标注块将真正改善你的写作。

带标题的提示

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

这是一个可以由用户展开的“折叠”警告标注块示例。你可以使用 collapse="true" 使其默认折叠，或使用 collapse="false" 使标注块默认展开。

此功能尚未在Revealjs演示文稿中可用（参见问题 1328）

Markdown语法

使用以下语法在Markdown中创建标注块（注意，标注块中使用的第一个Markdown标题用作标注块标题）：

::: {.callout-note}
请注意，有五种类型的标注块，包括：
`note`、`warning`、`important`、`tip` 和 `caution`。
:::

::: {.callout-tip}
## 带标题的提示

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

::: {.callout-caution collapse="true"}
## 展开以了解折叠

这是一个可以由用户展开的“折叠”警告标注块示例。你可以使用 `collapse="true"` 使其默认折叠，或使用 `collapse="false"` 使标注块默认展开。
:::

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

::: {.callout-tip title="带标题的提示"}
这是一个带有标题的标注块。
:::

自定义外观

折叠

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

外观

标注块有三种不同的外观可供选择。

default 默认外观，带有颜色的标题和图标。
simple 更轻量级的外观，不包括彩色标题背景。
minimal 最小化的处理，对标注块应用边框，但不包括标题背景颜色或图标。

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

callout-appearance: simple

或者通过在标注块上设置 appearance 属性。例如

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

## 注意

使用标注块是一种有效的方式来突出显示内容，使你的读者给予特别考虑或关注。

:::

显示为：

注意

使用标注块是一种有效的方式来突出显示内容，使你的读者给予特别考虑或关注。

图标

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

callout-icon: false

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

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

## 注意

使用标注块是一种有效的方式来突出显示内容，使你的读者给予特别考虑或关注。

:::

显示为：

注意

使用标注块是一种有效的方式来突出显示内容，使你的读者给予特别考虑或关注。

格式支持

以下格式如上所示渲染标注块：

  • HTML
  • PDF
  • MS Word
  • EPUB
  • Revealjs（不支持折叠选项） 请注意，当你禁用标准HTML主题时（例如，如果你指定了theme: none选项），HTML的标注渲染将不可用。此外，某些功能是特定于使用Bootstrap的文档的，例如可折叠标注，在其他文档中将无法工作。

当目标格式不支持标注时，它们将被渲染为一个带有粗体标题的简单引用块。

交叉引用

要交叉引用一个标注，请添加一个以适当标注前缀开头的ID属性（参见@tbl-callout-prefixes）。然后，您可以使用通常的@语法来引用该标注。例如，这里我们为标注添加了ID #tip-example，然后引用它：

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

添加一个以 `#tip-` 开头的ID以引用一个提示。
:::

参见 @tip-example...

这将呈现如下：

Tip 1: 交叉引用一个提示

添加一个以 #tip- 开头的ID以引用一个提示。

参见 Tip 1…

每种标注类型的前缀如下：

Table 1: 标注交叉引用的前缀
标注类型 前缀
note #nte-
tip #tip-
warning #wrn-
important #imp-
caution #cau-

目前，交叉引用标注仅支持HTML、PDF和MS Word格式。