{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"admonition-tag","__idx":0},"children":["Admonition tag"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use admonitions to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["add clarity"]}," to your content or ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["communicate important information"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"syntax-and-usage","__idx":1},"children":["Syntax and usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["admonition"]}," tag to wrap content."," ","Choose between the pre-built styles using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},"."," ","Optionally add a header with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stop!"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read me"]}," before moving on."]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stop! ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read me"]}," before moving on."]}]}],"rawContent":"{% admonition type=\"warning\" name=\"Important warning\" %}\n  Stop! **Read me** before moving on.\n{% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"attributes","__idx":2},"children":["Attributes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," ","Sets the type of admonition to info, warning, success, danger, or idea."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Adds a header to the admonition."," ","Transforms to ALL CAPS."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"admonition-types","__idx":3},"children":["Admonition types"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"class":"smaller-admonition-margins","type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," creates an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Info"]}," admonition."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"class":"smaller-admonition-margins","type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warning"]}," creates a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Warning"]}," admonition."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"class":"smaller-admonition-margins","type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," creates a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success"]}," admonition."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"class":"smaller-admonition-margins","type":"danger"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["danger"]}," creates a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Danger"]}," admonition."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"class":"smaller-admonition-margins","type":"idea"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idea"]}," creates an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idea"]}," admonition."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-relevant-information","__idx":5},"children":["Add relevant information"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Admonitions can be ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["distracting"]},"."," ","Consider how they ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["help users"]}," before adding them."]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Admonitions can be ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["distracting"]},"."," ","Consider how they ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["help users"]}," before adding them."]}]}],"rawContent":"  {% admonition type=\"info\" %}\n    Admonitions can be _distracting_.\n    Consider how they **help users** before adding them.\n  {% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"highlight-something-important","__idx":6},"children":["Highlight something important"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Read this!"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Users read admonitions ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["before"]}," content."," ","They can communicate essential information."]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Read this!"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Users read admonitions ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["before"]}," content."," ","They can communicate essential information."]}]}],"rawContent":"  {% admonition type=\"warning\" name=\"Read this!\" %}\n    Users read admonitions _before_ content.\n    They can communicate essential information.\n  {% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"communicate-urgency","__idx":7},"children":["Communicate urgency"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Careful"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't abuse admonitions or readers may ignore them."," ","You might need them to communicate something before a user makes an irreversible decision."]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"class":"wrapped-code-snippet","renderDemo":false,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Careful"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't abuse admonitions or readers may ignore them."," ","You might need them to communicate something before a user makes an irreversible decision."]}]}],"rawContent":"  {% admonition type=\"danger\" name=\"Careful\" %}\n    Don't abuse admonitions or readers may ignore them.\n    You might need them to communicate something before a user makes an irreversible decision.\n  {% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"suggest-an-optional-improvement","__idx":8},"children":["Suggest an optional improvement"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"idea","name":"Try this"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," to your admonitions to summarize the message."," ","Readers scan headers before they read the body text."]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"idea","name":"Try this"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," to your admonitions to summarize the message."," ","Readers scan headers before they read the body text."]}]}],"rawContent":"  {% admonition type=\"idea\" name=\"Try this\" %}\n    Add a `name` to your admonitions to summarize the message.\n    Readers scan headers before they read the body text.\n  {% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"celebrate-wins","__idx":9},"children":["Celebrate wins"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You made it to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last admonition example"]},"."," ","Hooray 🥳!"]}]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You made it to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last admonition example"]},"."," ","Hooray 🥳!"]}]}],"rawContent":"  {% admonition type=\"success\" name=\"Success\" %}\n    You made it to the **last admonition example**.\n    Hooray 🥳!\n  {% /admonition %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":10},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use in moderation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Overuse of admonitions reduces their effectiveness and users learn to ignore them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Don't use for page content"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Carefully consider the information you put in your admonitions."," ","If the information in admonitions doesn't add value and clarity or communicate something important, then they won't draw the reader's attention effectively."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use clear headers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use short, impactful headers that reflect the content to set the tone and encourage users to pay attention to the message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose the right type"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the admonition type that aligns with the nature of the content."," ","This alignment helps users understand ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["intent"]}," and recognize the level of urgency."," ","For example, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warning"]}," for cautionary information and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," for confirmation or positive feedback."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admonitions ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["after"]}," content"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Avoid using admonitions as the first element below headers or section headers."," ","Giving readers information to consider ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["before"]}," content adds to their cognitive load and reduces comprehension."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":11},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/learn/markdoc"},"children":["Markdoc overview for technical writers"]}]}," - Learn how to use Markdoc in your documentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags"},"children":["Markdoc tags"]}]}," - See the full list of supported Markdoc tags"]}]}]},"frontmatter":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"tagList":["admonition","configOptionRequirements","markdoc-example","table"],"title":"Admonition tag","lastModified":"2026-09-11T07:20:59.000Z"}