通知（宣传信息、备注、警告等）

DevSite 支持多种通知样式，以不同背景颜色的框格显示。背景颜色是预定义的，您可以使用 HTML 或 Markdown 创建通知。

可用的通知类型

备注

<aside class="note">
<b>Note:</b> An ordinary note.
</aside>

Note: An ordinary note.

提示

<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>

Tip: An ordinary tip.

注意

<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>

Caution: Suggests proceeding with caution.

警告

<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>

Warning: Stronger than caution; it means "Don't do this."

重要提示

<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>

Important: Defines an important concept.

要点

<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>

Key Point: Defines an important takeaway.

关键字

<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>

Key Term: Defines important terminology.

目标

<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>

Objective: Defines the goal of a procedure.

成功

<aside class="success">
<b>Success:</b> Describes a successful action or an error-free status.
Used only in interactive or dynamic content; don't use in ordinary
static pages.
</aside>

Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.

Beta 版

<aside class="beta">
<b>Beta:</b> A notice that describes a beta-release feature, which is
subject to change or removal in new minor versions of the product.
</aside>

Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.

预览

<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>

Preview: A note or tip for a feature preview.

Dogfood

<aside class="dogfood">
<b>Dogfood:</b> A notice that applies only temporarily, during internal
dogfood testing. Remove all Dogfood notices before making a document
publicly visible.
</aside>

Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.

已弃用

<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>

Deprecated: A note or tip for a deprecated feature, product, or service.

使用说明

HTML 使用

我们建议将这些类与 HTML5 <aside> 元素搭配使用，但您也可以改用其他块级元素（例如 <p>）。

HTML 类决定了通知的颜色和图标，但不会自动设置粗体显示的第一个字词；您需要手动编写该字词，如示例所示。从理论上讲，您可以使用与类对应的字词以外的字词，但我们建议您坚持使用上面显示的第一个字词。

在较旧的文档中，您可能会看到 class="special" 或非标准类名称，而不是 class="note"。这些类名称会生成与 note 通知在视觉上完全相同的通知，但我们建议您使用 class="note"，而不是使用特殊或非标准类名称。

Markdown 用法

Markdown 样式决定了通知的颜色和图标，并会自动设置通知的第一个字词为粗体。例如，Markdown 中的备注始终以粗体字的“备注：”开头。

对于包含多个段落的通知，请改用 HTML <aside>（和 <p>）。

您可能会看到“重要提示：”，而不是 Note:。这种 Markdown 样式会生成与 Note: 通知在视觉上完全相同的通知。

最佳做法

DevSite 建议您在向文档中添加通知时遵循以下最佳实践：

推荐

• 简明扼要（尽量将通知控制在一两句话内）。
• 请尽可能将每页的通知数量限制为 1 条（如有必要，可将每个版块的通知数量限制为 1 条）。
• 确保通知仅包含您要突出显示的重要内容；不要在通知中添加您不确定如何处理的内容。
• 在用户需要信息之前使用通知，而不是在用户需要信息之后使用。

不推荐

• 请勿在通知中添加代码示例、表格或图片。
• 避免将通知堆叠在一起，即使它们是不同类型的通知也是如此。
• 请尽量不要在标题后面立即插入通知。
• 请勿在流程之前使用通知来指定前提条件。

这些最佳实践在大多数情况下适用于类型为 note、caution 和 warning 的通知，但也可能适用于其他类型。

正面示例

力求简单：

在可能丢失数据的情况下使用 cautions：

使用 warning 时，请注意可能造成的伤害：

请为内容使用适当的通知类型，例如 key-term 或 success：

反面示例

通知不应过于冗长，也不应传达属于核心内容的信息：

通知不应在步骤之前指定前提条件（请改用“前提条件”部分）：