通知（コールアウト、メモ、警告など）

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.

ベータ版

<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="note" ではなく class="special" または標準以外のクラス名が使用されている場合があります。これらのクラス名は、note 通知と視覚的に同じ通知を生成しますが、特殊なクラス名や標準外のクラス名ではなく、class="note" を使用することをおすすめします。

Markdown の使用

Markdown スタイルによって、通知の色とアイコンが決まり、通知の最初の単語が自動的に太字になります。たとえば、Markdown のメモは常に「注:」という単語で始まり、太字で表示されます。

複数の段落を含む通知の場合は、代わりに HTML <aside>（および <p>）を使用します。

Note: の代わりに [重要] と表示される場合があります。この Markdown スタイルでは、Note: 通知と視覚的に同じ通知が生成されます。

ベスト プラクティス

DevSite では、ドキュメントに通知を追加する際は、次のベスト プラクティスに従うことをおすすめします。

推奨

• 簡潔に（通知は 1 ～ 2 文にまとめるように）
• 可能であれば、通知は 1 ページに 1 つ（必要に応じてセクションごとに 1 つ）に制限してください。
• 通知には、強調したい重要なコンテンツのみを含めます。どうすればよいかわからないコンテンツは通知に含めないでください。
• ユーザーが情報を必要とする前に、通知を使用してください。

非推奨

• 通知にコード例、表、画像を含めないでください。
• 種類が異なる場合でも、通知を重ねて表示しないでください。
• 見出しの直後に注意事項を挿入しないでください。
• 手順の前提条件を通知で指定しないでください。

これらのベスト プラクティスは、ほとんどの場合、note、caution、warning タイプの通知に適用されますが、他のタイプにも適用できます。

良い例

シンプルにする:

データが失われる可能性のある場合は cautions を使用します。

けがの可能性がある場合は warning を使用します。

コンテンツに適切な通知タイプ（key-term や success など）を使用します。

悪い例

通知は、冗長すぎたり、コア コンテンツに属する情報を伝えたりしないでください。

通知では、手順の前提条件を指定しないでください（代わりに「前提条件」セクションを使用してください）。