有些声明你可能希望通过将它们从内容流中取出并用优先级标记来引起注意。这些被称为警示。本页将介绍AsciiDoc提供的警示类型，如何将警示添加到文档中，以及如何使用图标或表情符号来增强它们。

警告类型

一个警示框的呈现样式是由分配的类型（即名称）确定的。AsciiDoc语言提供了五种警示框类型，分别用以下标签表示：

  • 注解

  • 提示

  • 重要

  • 注意

  • 警告

标签可以指定为块样式或作为特殊的段落前缀。除非启用了图标功能，否则标签会显示给阅读者看；如果启用了图标，则会在相应位置显示图标。

谨慎对比警告

在选择警示类型时，你可能会对“caution”和“warning”这两个词感到困惑，因为这两个词经常被交替使用。这里有一个简单的规则来帮助你区分这两者：

  • 使用*谨慎*来提醒读者小心行事（即，谨慎行动）。

  • 使用*警告*来告知读者存在的危险、伤害或后果。

要进行更深入的分析，请查看 https://www.differencebetween.com/difference-between-caution-and-vs-warning/。

警告语法

当你想要对一个段落特别强调时，就从你想用的标签开始编写该段落的第一行。这个标签必须是大写的，并且以冒号(:)结尾。

警告段落语法
Unresolved directive in admonitions.adoc - include::example$admonition.adoc[tag=para-c]

  1. 标签必须是大写字母，并且紧跟一个冒号(:)。

  2. 将段落的第一行与标签之间用一个空格分开。

显示下方的警告段落语法结果。

Unresolved directive in admonitions.adoc - include::example$admonition.adoc[tag=para]

当您想要对复杂内容应用一个警告时，在块上将标签设置为样式属性。如下一个例子所示，警告标签通常设置在示例块上。这种行为被称为*伪装*。当作为块上的属性设置时，标签必须是大写的。

警告块语法
Unresolved directive in admonitions.adoc - include::example$admonition.adoc[tag=bl-c]

  1. 在一个定界块上设置属性列表中的标签。标签必须是大写。

  2. 警告样式通常设置在示例块上。示例块由四个等号(====)分隔。

结果显示在下面。

Unresolved directive in admonitions.adoc - include::example$admonition.adoc[tag=bl-nest]

启用警告图标

在上述例子中，警告信息以带有标签样式的侧边栏呈现在一个callout盒子中。您可以通过在文档上设置`icons`属性并将其值赋为`font`，来用字体图标替换文本标签。

设置图标的警示段落
= 文档标题
图标字体

Unresolved directive in admonitions.adoc - include::example$admonition.adoc[tag=para]

了解更多关于在警告中使用 Font Awesome 或自定义图标的信息，请参阅macros:icons-font.html。

使用表情符号作为警告图标

如果没有基于图像或字体的图标可用，您可以利用警示说明标题来显示表情符号（或任何Unicode中的符号）来代替警示标签，从而为您提供另一种方式来制作警示图标。

如果文档中没有设置`icons`属性，那么警示标签将以文本形式显示（例如，CAUTION）。这个标签的文本来自于一个AsciiDoc属性。这个属性的名称是`<type>-caption`，其中`<type>`是小写的警示类型。例如，提示警示的属性是`tip-caption`。

你可以将一个Unicode字形分配给这个属性，而不是一个单词。

:tip-caption: 💡

[TIP]
可以使用Unicode字符作为警示图标。

这是你在HTML中得到的结果：

<td class="icon">
<div class="title">💡</div>
</td>

你可以不直接输入字符图形，而是输入一个字符引用。然而，由于你是在属性条目中定义字符引用，你（目前）必须禁用对值的替换。

:tip-caption: pass:[💡]

[TIP]
可以使用Unicode字符作为警示图标。

在GitHub上，AsciiDoc处理器输出的HTML经过一个后处理过滤器，该过滤器会用emoji表情符号替换emoji短代码。这意味着你可以在属性值中使用这些短代码代替。

ifdef::env-github[]
:tip-caption: :bulb:
endif::[]

在GitHub上可以使用表情符号作为警告图标。

当文档通过GitHub界面处理时，短代码会被替换为真正的表情符号。这是让警告图标在GitHub上工作的唯一已知方法。