通知 (醒目提示、附註、警告等)

DevSite 支援多種通知樣式，以不同背景顏色的方塊呈現。背景顏色已預先定義，您可以使用 HTML 或 Markdown 建立通知。

可用的通知類型

注意事項

HTML

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

Markdown

Note: An ordinary note.

訣竅

HTML

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

Markdown

Tip: An ordinary tip.

注意

HTML

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

Markdown

Caution: Suggests proceeding with caution.

警告

HTML

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

Markdown

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

重要事項

HTML

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

Markdown

Important: Defines an important concept.

重點

HTML

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

Markdown

Key Point: Defines an important takeaway.

重要字詞

HTML

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

Markdown

Key Term: Defines important terminology.

目標

HTML

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

Markdown

Objective: Defines the goal of a procedure.

成功

HTML

<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>

Markdown

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 版

HTML

<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>

Markdown

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

預覽

HTML

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

Markdown

Preview: A note or tip for a feature preview.

Dogfood 測試

HTML

<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>

Markdown

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

已淘汰

HTML

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

Markdown

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 中，註解一律會以粗體字體的「Note:」開頭。

如果通知包含多個段落，請改用 HTML <aside> (和 <p>)。

您可能會看到「Important:」而非「Note:」。這類 Markdown 樣式會產生與 Note: 通知相同的視覺效果。

最佳做法

DevSite 建議您在文件中加入通知時，遵循下列最佳做法：

建議

  • 請簡明扼要 (盡量將通知縮短到一或兩句話)。
  • 盡可能將通知限制為每頁一則 (或視需要每個區塊一則)。
  • 請確保通知中只包含您想強調的重要內容，不要將不確定如何處理的內容納入通知。
  • 請在使用者需要資訊之前發出通知，而不是在使用者需要資訊之後。

不建議採用

  • 請勿在通知中加入程式碼範例、表格或圖片。
  • 避免堆疊通知，即使是不同類型的通知也一樣。
  • 請勿在標題後立即插入通知。
  • 請勿在程序前使用通知來指定先決條件。

這些最佳做法大多適用於 note、caution 和 warning 類型的通知，但也適用於其他類型。

正確範例

保持簡單：

使用 cautions 表示資料可能會遺失：

使用 warning 表示潛在的傷害：

請為內容使用適當的通知類型，例如 key-term 或 success：

錯誤範例

通知不應過於冗長，也不應傳達屬於核心內容的資訊：

通知不應在程序前指定先決條件 (請改用「先決條件」部分)：