Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

Callouts are visual interrupts. They break the flow of reading so people notice them, stop, and pay attention. And since they’re defined components, callouts can signal the same information to AI agents. But what exactly is the signal you’re sending? That depends on which type of callout you use. If you use callouts inconsistently, you’ll send mixed messages and make it difficult for readers to build a mental model of your content. The main takeaway: use callouts consistently and purposefully. Types carry meaning so treat them as vocabulary, not decoration.

​
The types of callouts

While you can use callouts however you like, always use them consistently. And consider how the label affects the reader’s perception of the content. Here are some general guidelines for when to use each type of callout:
ComponentSignalUse when
<Note>Neutral additionThere’s something useful to know that doesn’t fit in the main flow.
<Info>Informational emphasisYou need to draw attention to a fact, definition, or caveat like a permission or prerequisite.
<Tip>Optional improvementThere’s a best practice or shortcut the reader might not discover on their own.
<Warning>Caution requiredSomething could break or cause data loss if the reader misses this.
<Danger>Serious harm possibleIgnoring this information or doing this action incorrectly is destructive, irreversible, or security-critical.
<Check>ConfirmationThe reader has completed something correctly, or a requirement has been satisfied.

​
How to choose

Ask yourself, “What happens if the reader skips this callout?”
  • Nothing bad, they just miss something useful → <Tip> or <Note>
  • They might be confused or have a worse experience → <Info>
  • Something breaks or data gets corrupted → <Warning>
  • Data gets lost, accounts get compromised, or something irreversible happens → <Danger>
The <Check> callout is different. Use it to give users confirmation after they complete a task. Use the other callout types to guide users before they take an action or make a decision.
Example of a <Check> callout
<Check>
  Your API key is now active. Verify this by checking the **Keys** section of your dashboard.
</Check>

​
The note versus info distinction

These two are easy to conflate. If you use them consistently, your users learn to expect the same signal from each. Notes and info callouts can signal different intent.
  • <Note> is a side thought. “By the way, you might want to know this.”
  • <Info> is a direct call to attention. “Make sure you understand this.”
If you want to point out that a feature behaves differently in a specific context, that’s probably an info callout. If you’re adding an aside about something tangentially related, that’s a note. In practice, many documentation sites pick one and use it consistently rather than trying to draw a precise line. What is more important is that you reserve warning and danger callouts for actual risk.

​
Don’t escalate to sound important

The most common callout mistake is using a warning because the content feels significant, but there’s no actual risk for the user. If you’re using <Warning> to emphasize a default setting or note an API behavior, you’re training readers to ignore your warnings. Reserve warning and danger callouts for potentially destructive actions or situations where data could be lost or compromised. If you can describe the worst-case outcome and it’s “your request fails with a 400 error,” that’s not worthy of a warning or danger callout. If the worst-case is “all data in this environment is permanently deleted,” that’s danger.
Next up: When callouts stop working — What happens when you use too many callouts and how to fix it.