Admonitions
Use admonitions to capture the reader’s attention.
Admonitions stand out from the main body of text to capture the reader’s attention on something important. For their nature, they break the reading flow and are perceived as a distraction by readers.
This is why they should be used only when it is necessary.
Do not overuse admonitions.
If they appear frequently, the reader will think that they don't contain important information, so they will skip them.
When you use them, keep these recommendations in mind:
- If the admonition is about a specific step, place it inside the step.
- If the admonition is generic about a topic, place it at the beginning of the topic.
- If the admonition is a generic consideration after a series of steps, place it at the end of the topic.
- Never start a section with an admonition.
- Never place two admonitions next to each other.
- Don't nest admonitions.
# Admonition types
Use three admonition types: Notes, Warnings, and Best Practices.
# Tip
Also known as "best practice" or "hint", it conveys the possibility to enhance the user experience by implementing the recommendations it contains.
Tip
This is a "tip" admonition, use it to give recommendations and best practices that will enhance the user experience.
# Info
Also known as "note" or “notice”, it contains generic contextual and additional info about requirements and technical limitations. It also conveys the possibility of soft errors when the recommendations contained are not followed.
Info
This is a "info" admonition. Use it to give information about limitations, additional considerations, or warn the user about possible soft errors.
# Warning
Also known as "danger", “alert” or “caution”, it alerts the reader about the possibility of fatal errors, human damage, and consequent liability if caution is not used or if the recommendations contained are not followed.
Warning
This is a "warning" admonition. Use it to warn the user about possible fatal errors and possibility of service disruption.