Callouts and Admonitions

Callouts or admonitions emphasize important or helpful information. To avoid clutter on the page and to preserve visual impact, use callouts sparingly.

Callout Anatomy

A callout contains the following parts:

Label that indicates the callout type
Optional title
Body text

click to enlarge

Callout Types

You can use the following callouts:

Callout Type	Description	Directive
Tip	Provides useful information that might improve product performance or make procedures easier to follow. Tips provide the following benefits: Help users learn techniques or procedures Show alternative ways of doing something Provide shortcuts Provide helpful (but not essential) information	`.. tip:: <title>`
Note	Provides information that emphasizes or supplements information in the text. A note can provide information that applies only in certain cases.	`.. note:: <title>`
Important	Presents an important or essential point. As a rule, users must pay attention to important callouts to complete a task or understand a topic.	`.. important:: <title>`
Warning	Alerts users to potential hazards or highlights critical information. Use a warning for situations in which users could lose data, compromise data integrity, or disrupt operations if they don't follow instructions carefully.	`.. warning:: <title>`

Callout Guidelines

When you create callouts, use the following guidelines:

Use the appropriate callout type to convey the kind of information you want to communicate.
Don't stack multiple callouts directly after one another, as these can distract users. To avoid stacking callouts, group supplemental information from callouts into a dedicated section. For callouts of the same type, use a single callout that contains separate paragraphs or an unordered list.
If possible, don't use callouts in tables and option lists. Callouts reduce the scannability of tables and options lists.
Avoid nesting callouts inside tables, code blocks, and other elements.
Place a callout as close as possible to the information that it emphasizes or clarifies.
Use callouts for long form text and avoid using callouts for links only.
Use callouts only when needed and avoid overcrowding the page with callouts.

The following callouts might appear in existing documentation but are deprecated. Don't use these callouts in new content:

.. admonition::
.. caution::
.. danger::
.. example::
.. see::
.. see also::
.. topic::

Nested Components

Don't nest components. To learn more, see Nested Components Guidelines.

Back

Collapsible Sections

Capitalization