Skip to main content
Callouts appear inside your content and interrupt the reading flow. But some information needs to exist outside the content entirely when it applies to the whole site, is relevant to the sidebar navigation, or it marks up something inline without stopping the reader. Use banners, tags, and badges to handle these three cases. A <Banner> appears at the top of the page, above all content. Configure it in docs.json and choose whether it is dismissable or not. Use a banner when:
  • You’re announcing a deprecation that affects a significant portion of your users.
  • A feature is in maintenance mode or temporarily unavailable.
  • There’s a breaking change in an upcoming release that everyone needs to know about before they continue reading.
Defining characteristics of banners are that they’re timely and relevant to the majority of your users.
Example of a banner in docs.json
{
  "banner": {
    "content": "API v1 is deprecated and will be removed on March 31. [Migrate to v2](/guides/migrate-v2) before that date.",
    "dismissible": true
  }
}

​
When not to use a banner

If an announcement is only applicable to a small portion of your users, don’t use a banner. Don’t use a banner for:
  • A new feature announcement that isn’t urgent or widely relevant (write a changelog entry instead).
  • Page-specific notes or warnings (use a callout instead).
  • Content that applies to only some users (the banner appears to everyone).
The cost of a banner is high: it takes up space on every page and if it’s not relevant to people, it trains them to dismiss banners without reading them. Use banners thoughtfully, and retire them promptly.

​
Tag: sidebar labels for pages

The tag frontmatter property adds a short label next to your page title in the sidebar. Use it to signal the status of a page to readers before they open it.
Example of a tag
---
title: "Streaming responses"
tag: "New"
---
Tags are useful for:
  • Marking new pages or recently updated content so returning users notice them.
  • Labeling preview or beta features that aren’t yet stable.
For deprecated pages, Mintlify has a specific frontmatter property: deprecated: true.
Example of a deprecated page
---
title: "Legacy authentication"
deprecated: true
---
This displays a “Deprecated” label in the sidebar and on the page itself.

​
Badge: inline labels and status indicators

Use <Badge> components to communicate status, version, or category inline with your content.
Example of a badge
## Streaming responses <Badge color="green">New</Badge>

Streaming is now available for all API tiers.
Common uses for badges are:
  • Versions and availability: Available in v2.3+
  • Status indicators: Beta, Deprecated, Enterprise
  • Requirements and defaults: Required, Optional, Default

​
Tags versus badges

Both tags and badges are labels, but they appear in different places and serve different readers. A tag is a sidebar signal. It’s visible before the reader opens a page and useful for readers scanning navigation. A badge appears inside the content and labels something at the point where the reader encounters it. The right choice depends on when the reader needs the information: in the sidebar while navigating or in the content while reading.
Next up: Steps or numbered lists — How to decide when a procedure warrants the steps component and when a simple numbered list works better.