Admonitions and text callouts

Admonitions visually highlight essential information, helping readers notice important details, avoid errors, and understand content better. Use them sparingly to maintain their effectiveness.

Admonitions and text callout boxes let you visually highlight information by surrounding text with a colored box and an icon. When used carefully, these admonitions help readers notice important details, avoid errors, and better understand content. Use each type of admonition for its intended purpose, and avoid overusing text callout boxes so readers don't start ignoring them.

Before you include an admonition

Before adding one or more admonitions to a topic, consider the visual impact they have on the page. Too many callouts can distract readers and make topics hard to scan.

Use admonitions only when the information is essential and cannot be easily integrated into the surrounding text. Otherwise, consider weaving that information into the content or as part of the instructions you're creating.

Guidelines for using admonitions

Follow these guidelines when you use callout boxes:

Don't place an admonition immediately after a topic title.
Don't use an admonition in place of prerequisites.
Avoid writing long or detailed text in an admonition.
Place an admonition after the text it refers to. For steps in a task, include the callout before the step if the user needs that information to proceed safely.
Include links in admonitions only if the link is essential to the task or a reader's understanding of the content.

Types of admonitions

Review the following table for guidance on when to use each type of admonition:


Admonition	Purpose	When to use	Example
Caution	Alerts users to critical information that they can't reverse if they continue with the task.	To warn a user of data loss To warn a user that an action can corrupt their data To let a user know that there's a consequence they can't reverse To tell a user to back up their data before they continue	CAUTION: The process of adding an instance to a search head cluster overwrites any configurations or apps currently on the instance.
Note	Provides an important piece of information or a tip that isn't an integral part of the content but that adds clarity or more information.	To supplement a point in the main text To supply information that applies in special cases To suggest alternative methods	Note: Use per-result triggering carefully. If a peer is not available, a real-time search won't warn you that the search might be incomplete. To avoid this issue, use a scheduled alert instead.
Warning	Draws attention to potential hazards or unsafe actions that might damage equipment or systems.	To warn about incompatible versions or unsupported actions To highlight steps that prevent major errors	Warning: Automatic instantiation is the only compatible instantiation with this interface. All other interfaces require manual instantiation or else you might face data loss.