#Badges & Statuses

Badges are small labels — ALPHA, WIP, Deprecated — attached to a page. They render in both the sidebar (next to the page's nav item) and the breadcrumb (right of the trail). Attach one two ways:

• badge — an ad-hoc label defined inline on the page.
• status — a reference to a named, documented preset in the status registry.

---
title: Streaming API
status: alpha # named status → Alpha chip + its description tooltip
badge: v2 # ad-hoc badge, renders alongside
---

This is the page-level badge. It is distinct from the inline <Badge> component you drop into markdown content.

#badge

An ad-hoc badge. Accepts a string shorthand, a full object, or an array of either.

---
badge: ALPHA # shorthand → neutral chip
---

---
badge:
  - { text: WIP, variant: warning, tooltip: Work in progress }
  - v2
---

BadgeVariant is one of info, success, warning, danger, neutral.

#status

A status is a named badge preset — define the label, meaning, and color once; reference it by id everywhere. Reference one (or several) with the status field:

---
status: beta
---

---
status: [beta, internal]
---

The status's title becomes the chip text, its color/variant the color, and its description the hover tooltip.

#Built-in statuses

Shipped by default, with theme-aware variants:

#Custom statuses

Define or override statuses in the top-level statuses config. Entries merge over the built-ins by id — a matching id overrides, a new id extends.

defineConfig({
  statuses: [
    // override a built-in
    {
      id: 'alpha',
      title: 'Alpha',
      description: 'Early access — expect changes.',
      variant: 'warning',
    },
    // add your own (raw color)
    {
      id: 'design-partner',
      title: 'Design Partner',
      description: 'Available to design partners only.',
      color: '#7c3aed',
    },
  ],
})

#Glob rules

Apply a badge or status to many pages by route without touching each file. Rules live under badges.rules; each rule needs a match and at least one of badge or status.

defineConfig({
  badges: {
    rules: [
      { match: '/api/experimental/**', status: 'alpha' },
      { match: ['/v2/**', '/beta/**'], badge: { text: 'v2', variant: 'info' } },
    ],
  },
})

match supports * (one path segment), ** (any depth), and ? (one character).

#Precedence

A page's badge comes from the first of these that resolves — sources do not merge across tiers:

1. the page's own frontmatter (badge / status),
2. an inherited defaults badge/status on a parent Page or Workspace,
3. a matching glob rule.

Within a single source, status and badge both render.

#Where badges render

#References

• Configuration — the badges and statuses config keys
• Frontmatter Fields — the badge and status page fields
• <Badge> component — the inline badge for markdown content