# Page Status Badges
Documentation pages have a lifecycle. Some pages describe brand-new features, others cover APIs that are experimental and subject to change, and some document capabilities that are being phased out. Communicating this status helps readers set expectations before they invest time in a page.
Great Docs lets you mark pages with a lifecycle status such as "New", "Beta", or "Deprecated". Status badges appear as colored indicators in two places:
1. **Below the page title**: a full badge with icon, label, and description
2. **In sidebar navigation**: a compact icon next to the link, with a tooltip on hover
Status badges are disabled by default. To enable them, add a `page_status` section to `great-docs.yml`:
great-docs.yml
``` yaml
page_status:
enabled: true
```
Or use the shorthand:
great-docs.yml
``` yaml
page_status: true
```
# Adding a Status to a Page
Set the `status` key in the YAML frontmatter of any user guide, recipe, or custom section page:
user_guide/03-migration.qmd
``` yaml
---
title: "Migration Guide"
status: deprecated
---
```
The value must match one of the defined status keys (see below). Pages without a `status` key display no badge.
# Built-in Statuses
Great Docs ships with five built-in statuses, each with a [Lucide](https://lucide.dev/icons/) icon, color, and description:
| Key | Label | Icon | Color | Description |
|----|----|----|----|----|
| `new` | New | `sparkles` | Green | Recently added |
| `updated` | Updated | `refresh-cw` | Blue | Recently updated |
| `beta` | Beta | `flask-conical` | Amber | Beta feature |
| `deprecated` | Deprecated | `triangle-alert` | Red | May be removed in a future release |
| `experimental` | Experimental | `beaker` | Purple | API may change without notice |
Here is how these five statuses look as page-level badges:
✦ New -- Recently added
↻ Updated -- Recently updated
⚗ Beta -- Beta feature
⚠ Deprecated -- May be removed in a future release
 Experimental -- API may change without notice
All built-in status labels and descriptions are automatically translated when the site uses a non-English language (see [Internationalization](internationalization.md)).
# Custom Statuses
The five built-in statuses cover common lifecycle stages, but your team may have its own workflow. You can add your own statuses or override built-in ones via the `statuses` map in `great-docs.yml`:
great-docs.yml
``` yaml
page_status:
enabled: true
statuses:
draft:
label: "Draft"
icon: pencil
color: "#6b7280"
description: "Work in progress"
review:
label: "In Review"
icon: eye
color: "#0ea5e9"
description: "Awaiting technical review"
```
Each custom status definition accepts:
| Key | Type | Required | Description |
|----|----|----|----|
| `label` | string | No | Display text (defaults to the key in title case) |
| `icon` | string | No | Lucide icon name (e.g., `pencil`, `eye`) |
| `color` | string | No | CSS color for the badge (defaults to `#6b7280`) |
| `description` | string | No | Short explanation shown on the page badge and as a tooltip |
Custom statuses use their literal `label` and `description` values in all languages. Only the five built-in statuses are translated automatically.
Use the custom key in frontmatter just like a built-in status:
user_guide/10-new-api.qmd
``` yaml
---
title: "New API Design"
status: draft
---
```
# Overriding Built-in Statuses
To change a built-in status (for example, switching the icon or color for `deprecated`), redefine it in `statuses`:
great-docs.yml
``` yaml
page_status:
enabled: true
statuses:
deprecated:
label: "Legacy"
icon: archive
color: "#9ca3af"
description: "Superseded by a newer approach"
```
Your definition fully replaces the built-in default for that key. Any fields you omit fall back to their defaults (gray color, title-cased label, no icon).
# Controlling Where Badges Appear
By default, badges are shown in both locations. You can disable either one independently if you prefer a subtler approach.
## Sidebar Only
great-docs.yml
``` yaml
page_status:
enabled: true
show_on_pages: false # No badge below the title
show_in_sidebar: true # Icon in sidebar (default)
```
## Page Title Only
great-docs.yml
``` yaml
page_status:
enabled: true
show_on_pages: true # Badge below the title (default)
show_in_sidebar: false # No icon in sidebar
```
# How It Looks
## On the Page
The page-level badge appears directly below the title (and subtitle, if present). It displays the status icon, label, and description in the status color:
Getting Started
A quick introduction to the package
✦ New -- Recently added
## In the Sidebar
Sidebar links for pages with a status show a small colored pill after the link text. Hovering over the pill displays a tooltip with the full label and description:
Getting Started
Migration Guide
Configuration
New API Design
Pages without a status display no indicator, keeping the sidebar clean.
# Which Pages Are Scanned?
Great Docs scans for `status` frontmatter in `.qmd` files found in:
- **User guide** pages (`user-guide/`)
- **Recipes** pages (`recipes/`)
- **Custom sections** (any section defined in `sections:` config)
API reference pages, the changelog, and index pages are not scanned. This keeps badges focused on content pages where lifecycle status is meaningful.
# Full Configuration Reference
Here is the complete `page_status` configuration with all options and their defaults:
great-docs.yml
``` yaml
page_status:
enabled: false # Master switch (default: false)
show_in_sidebar: true # Show icon in sidebar links (default: true)
show_on_pages: true # Show badge below page titles (default: true)
statuses: # Status definitions (built-ins shown below)
new:
label: "New"
icon: sparkles
color: "#10b981"
description: "Recently added"
updated:
label: "Updated"
icon: refresh-cw
color: "#3b82f6"
description: "Recently updated"
beta:
label: "Beta"
icon: flask-conical
color: "#f59e0b"
description: "Beta feature"
deprecated:
label: "Deprecated"
icon: triangle-alert
color: "#ef4444"
description: "May be removed in a future release"
experimental:
label: "Experimental"
icon: beaker
color: "#8b5cf6"
description: "API may change without notice"
```
# Tips
A few guidelines help keep status badges effective across your documentation.
- **Use statuses sparingly**: a page should carry a status only when it communicates something actionable. If every page is "New", the badge loses its value.
- **Remove stale statuses**: revisit `status: new` and `status: updated` periodically and remove them once the content is no longer recent.
- **Combine with tags**: statuses and tags serve different purposes. Tags categorize content by topic; statuses communicate lifecycle. A page can have both.
- **Custom statuses for workflows**: define statuses like `draft` or `review` to track editorial progress while keeping the documentation published.
# Next Steps
Status badges communicate lifecycle information at a glance. They work best when used selectively for pages that are genuinely new, recently updated, or approaching deprecation.
- [Page Tags](page-tags.md) categorizes pages by topic with filterable tag listings
- [API Evolution](api-evolution.md) tracks changes across releases at the API level
- [Internationalization](internationalization.md) covers how built-in badge labels are translated
- [Configuration](configuration.md) covers all status badge settings in `great-docs.yml`