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 should be strong signals to users that they ought to pay attention. But if you oversue callouts, they become visual noise that readers skip past. This is callout fatigue, and it’s one of the most common ways well-intentioned documentation becomes harder to read.

​
When callout fatigue happens

Callout fatigue usually builds gradually. Each callout is justifiable on its own, but together they create a block of styled text that readers skip past since it’s hard to quickly read and understand. Or what starts as a consistent use of callouts expands until the same callout types are used differently across pages, so readers don’t know what to expect from a callout and start ignoring them. This creates multiple problems.
  • When something is genuinely dangerous, people might ignore a warning because it looks like every other callout with less important information.
  • AI tools might not understand the context of the callout and provide inaccurate information.
  • Content outside of the callouts becomes hard to read because callouts create too much distraction.
To avoid visual clutter and retain the emphasis of callouts, never stack multiple callouts in a row.

​
How many callouts to use

There’s no hard rule on the right number of callouts. Your content and your users have unique needs that you must consider. But a useful heuristic is if a page has more than two callouts, examine what each one is meant to accomplish. Questions to ask for each callout:
  • Would a reader encounter a problem if they didn’t see this?
  • Does this need to be visually separated from the main content, or should it be part of another section?
  • Is this callout covering for other writing that could be more clear?
Callouts are sometimes used to fix problems introduced by other content. Instead of rewriting a paragraph, someone adds a <Note> explaining a caveat. Over time these callouts accumulate. Often, the fix is to revise the main text of a page instead of adding another callout.

​
Main ideas should be in the main content

Putting very important information inside callouts can feel like the right choice because the styling of callouts makes it look significant. But separating information into callouts can have the opposite effect and make the information less visible if readers skip past the callouts. If users need to know something to complete the task, that information belongs in the procedure. Reserve callouts for things that apply to a subset of users, edge cases, or genuine risks. When readers skip past callouts and miss something important, that’s a writing problem, not a reader problem. This is especially common in setup guides:
Example of a poorly used callout
{/* Users need to know where to save their environment variables earlier in the procedure. */}
1. Copy your API key from your Mintlify dashboard.
2. Replace `your-key` with your actual key: `API_KEY=your-key`
3. Restart your development server so that the new environment variable loads.

<Note>
  Set your environment variables in your `.env` file.
</Note>

​
Multiple callouts on the same page

If you find yourself writing three <Warning> callouts on a single page, stop and examine the content itself. Multiple warnings on one page can indicate:
  • The feature has too many dangerous edge cases and the documentation is papering over a product problem.
  • The procedure is too long and should be split into smaller pages.
  • Some of the warnings aren’t actually <Warning> level and should be downgraded or removed.
This applies to all callout types. If you ever notice that you’re using many callouts on the same page, take a step back and think about the content itself. You can always return to the key questions that will help you right high quality documentation: what are my users trying to do while they read this and how do I help them do it correctly?
Next up: Site-wide and inline signals — How banners, tags, and badges help emphasize information site-wide, at the page-level, and inline.