The admonition tag calls your users' attention to a specific piece of information by placing it inside a pre-styled banner, separate from the main content.
Use admonitions to add clarity to your content or communicate important information.
Use the admonition tag to wrap content. Choose between the pre-built styles using type. Optionally add a header with name.
Stop! Read me before moving on.
{% admonition type="warning" name="Important warning" %}
Stop! **Read me** before moving on.
{% /admonition %}| Attribute | Type | Description |
|---|---|---|
type | String | Required. Sets the type of admonition to info, warning, success, or danger. Examples below. |
name | String | Adds a header to the admonition. Transforms to ALL CAPS. |
Type info creates an Info admonition.
Type warning creates a Warning admonition.
Type success creates a Success admonition.
Type danger creates a Danger admonition.
Admonitions can be distracting. Consider how they help users before adding them.
{% admonition type="info" %}
Admonitions can be _distracting_. Consider how they **help users** before adding them.
{% /admonition %}Users read admonitions before content. They can communicate essential information.
{% admonition type="warning" name="Read this!" %}
Users read admonitions _before_ content. They can communicate essential information.
{% /admonition %}Don't abuse admonitions or readers will ignore them. You might need them to communicate something before a user makes an irreversible decision.
{% admonition type="danger" name="Careful" %}
Don't abuse admonitions or readers will ignore them. You might need them to communicate something before a user makes an irreversible decision.
{% /admonition %}You made it to the last admonition example. Hooray 🥳!
{% admonition type="success" name="Success" %}
You made it to the **last admonition example**. Hooray 🥳!
{% /admonition %}Use in moderation Overuse of admonitions will reduce their effectiveness and users will learn to ignore them.
Don't use for page content Carefully consider the information you put in your admonitions. They should add value and clarity or communicate something important. If readers don't know what to expect, then admonitions won't draw their attention effectively.
Use clear headers Use short, impactful headers that reflect the content to set the tone and encourage users to pay attention to the message.
Choose the right type Select the admonition type that aligns with the nature of the content. This helps users understand intent and recognize the level of urgency. For example, you should use warning for cautionary information and success for confirmation or positive feedback.
Admonitions after content Avoid using admonitions as the first element below headers or section headers. Giving readers information to consider before content adds to their cognitive load and reduces comprehension.