Collections

Badges

How to use badges to indicate status on collections, pages, and navigation items.

Overview

Badges provide visual status indicators throughout the documentation portal. They can be applied at three levels:

Level	Where It Appears	How to Configure
Collection	Homepage grid, collections menu	`collections.ts` → `navigation.badge`
Page	Page header, MCP metadata	Page frontmatter → `badge` or `badges`
Navigation	Sidebar navigation tree	Page frontmatter → `navigation.badge`

Page-level badges (badge / badges) serve double duty: they render visually in the page header and are returned as metadata labels in MCP tool responses (list-pages, get-page). This allows AI agents to see page status without fetching full content.

Badge Presets

String shortcuts are automatically expanded to full badge configurations. Badges are organized into functional categories:

Maturity / Lifecycle

Indicate the development stage of documentation or features:

Shorthand	Label	Color	Variant	Use Case
`alpha`	Alpha	error	subtle	Early development, expect breaking changes
`beta`	Beta	warning	subtle	Feature complete but still testing
`experimental`	Experimental	warning	subtle	Proof of concept, may be removed
`production`	Production	success	subtle	Stable and recommended for use
`deprecated`	Deprecated	error	solid	Still works but don't use for new projects

Document Status

Track the editorial lifecycle of documentation:

Shorthand	Label	Color	Variant	Use Case
`draft`	Draft	neutral	outline	Work in progress, incomplete
`rfc`	RFC	info	outline	Request for comments, seeking feedback
`review`	Review	warning	outline	Under review, awaiting approval
`approved`	Approved	success	outline	Reviewed and approved
`archived`	Archived	neutral	subtle	Historical reference, no longer maintained

Change Indicators

Highlight recent updates:

Shorthand	Label	Color	Variant	Use Case
`new`	New	success	solid	Recently added content
`updated`	Updated	success	subtle	Recently modified content

MCP Visibility

Control content exposure to MCP (Model Context Protocol) tools:

Shorthand	Label	Color	Variant	Behavior
`nomcp`	No MCP	neutral	outline	Hidden from MCP queries, visible in UI
`mcponly`	MCP Only	neutral	outline	Visible to MCP, hidden from UI navigation

MCP visibility badges are behavioral — they affect how content is exposed to AI assistants and users:

nomcp: Hidden from MCP tool queries (list-pages, get-page), but visible in UI and search.
mcponly: Visible to MCP tools, but filtered from sidebar navigation and the search index.

Special

Shorthand	Label	Color	Variant	Use Case
`local`	Local Preview	primary	solid	Content only visible in local development

Collection Badges

Collection badges appear on the homepage grid and in the collections dropdown menu. They indicate the overall status of an entire documentation collection.

Configuration

Add a badge property to the collection's navigation object in collections.ts:

// collections.ts
export const collectionsSpec = {
  schemas: {
    prefix: '/schemas',
    source: { repository: 'https://github.com/ontopix/schemas', include: 'doc/**/*.md' },
    frontpage: '/schemas/readme',
    navigation: {
      title: 'Schemas',
      description: 'Data schemas and type definitions.',
      icon: 'i-lucide-database',
      badge: 'Draft'  // String shorthand
    }
  },
  stylebook: {
    prefix: '/stylebook',
    source: { repository: 'https://github.com/ontopix/stylebook', include: 'packages/content/**/*.md' },
    frontpage: '/stylebook/',
    navigation: {
      title: 'Stylebook',
      description: 'Design system and UI components.',
      icon: 'i-lucide-palette',
      badge: {  // Full BadgeProps object
        label: 'Experimental',
        color: 'warning',
        variant: 'subtle'
      }
    }
  }
} as const

Page Badges

Page badges appear in the page header (below the title) and are included as metadata in MCP responses. They indicate the status of a specific documentation page.

Both badge (single) and badges (array) accept either a string shorthand or a full BadgeProps object. When both are present, they are merged into a single list.

Configuration

Add badge or badges to the page's frontmatter:

---
title: My Feature
description: Documentation for my feature.
badge: Beta
---

For multiple badges:

---
title: My Feature
description: Documentation for my feature.
badges:
  - Beta
  - Updated
---

Or with full control:

---
title: My Feature
description: Documentation for my feature.
badge:
  label: Breaking Changes
  color: error
  variant: solid
badges:
  - label: v2.0
    color: primary
    variant: outline
---

Accessing Badges in Components

The useContentItem() composable returns normalized badges ready for use with UBadge:

<script setup lang="ts">
const { page, badges } = await useContentItem()
</script>

<template>
  <div>
    <h1>{{ page.title }}</h1>
    <div class="flex gap-2">
      <UBadge v-for="(badge, i) in badges" :key="i" v-bind="badge" />
    </div>
  </div>
</template>

Navigation Badges

Navigation badges appear in the sidebar navigation tree next to page titles. This is a Nuxt Content built-in feature — it only supports a single badge (not an array).

Navigation badges (navigation.badge) are independent from page badges (badge / badges). A page can have multiple badges in its header while showing a different single badge in the sidebar.

Configuration

Add a badge property inside the navigation object in frontmatter:

---
title: Authentication
description: How authentication works.
navigation:
  icon: i-lucide-lock
  badge: New
---

With full badge props:

---
title: Deprecated API
description: Legacy API documentation.
navigation:
  icon: i-lucide-alert-triangle
  badge:
    label: Deprecated
    color: error
---

Full BadgeProps

When you need full control, use the complete Nuxt UI Badge props:

badge:
  label: Custom        # Required: display text
  color: primary       # primary, secondary, success, warning, error, info, neutral
  variant: solid       # solid, outline, subtle, soft
  size: sm             # xs, sm, md, lg
  class: my-custom     # Additional CSS classes

Any unrecognized string becomes a neutral subtle badge with the string as label.

Use Cases

Status Lifecycle

Show documentation maturity progression:

# Early development
badge: alpha

# Active development
badge: beta

# Proof of concept
badge: experimental

# Stable and recommended
badge: production

# End of life
badge: deprecated

Document Workflow

Track editorial status:

# Initial draft
badge: draft

# Seeking feedback
badge: rfc

# Under review
badge: review

# Approved for publication
badge: approved

# Historical reference
badge: archived

Highlighting Changes

Draw attention to updates:

# Recently added page
badge: new

# Recently modified
badge: updated

# Contains breaking changes
badge:
  label: Breaking
  color: error
  variant: solid

MCP Visibility Control

Control AI assistant access:

# Hide from MCP tools (internal docs, sensitive info)
badge: nomcp

# Show only to MCP (AI-specific guidance)
badge: mcponly

Implementation Details

Badges are normalized by shared/collectionUtils.ts:

import type { BadgeProps } from '@nuxt/ui'

export type Badge = string | Partial<BadgeProps>

export function normalizeBadge(badge: Badge): Partial<BadgeProps> {
  if (typeof badge === 'string') {
    const preset = badgePresets[badge.toLowerCase()]
    return preset ?? { label: badge, color: 'neutral', variant: 'subtle' }
  }
  return badge
}

export function getAllBadges(item: { badge?: Badge, badges?: Badge[] }): Partial<BadgeProps>[] {
  const result: Partial<BadgeProps>[] = []
  if (item.badge) result.push(normalizeBadge(item.badge))
  if (item.badges) result.push(...item.badges.map(normalizeBadge))
  return result
}

MCP Visibility Helpers

// Check if content should be hidden from MCP
export function isHiddenFromMcp(item: { badge?: Badge, badges?: Badge[] }): boolean {
  return hasBadge(item, 'nomcp')
}

// Check if content should be hidden from UI
export function isHiddenFromUi(item: { badge?: Badge, badges?: Badge[] }): boolean {
  return hasBadge(item, 'mcponly')
}

The useContentItem() composable automatically normalizes page badges and exposes them as a computed property.

Collection Architecture

How collections are defined and managed in the codebase.

Data Collections

How to import and use structured data alongside documentation content.