Product Configuration

When your documentation covers multiple products (like an API, SDK, and CLI), each product gets its own folder with a _product_.json file. This file controls how the product appears in the product switcher and how it behaves.

Place the file at the root of a product folder:

1docs/
2├── api/
3│   ├── _product_.json    ← product config
4│   ├── v1.0.0/
5│   └── v2.0.0/
6├── sdk/
7│   ├── _product_.json
8│   └── v1.0.0/

Basic Configuration

Here's a minimal _product_.json:

1{
2  "label": "REST API"
3}

The label is the only required field — it's the display name shown in the product switcher dropdown.

Complete Example

A fully configured product:

1{
2  "label": "REST API",
3  "icon": "cloud",
4  "description": "Complete reference for the REST API endpoints",
5  "activeVersion": "v2.0.0",
6  "badge": "New",
7  "position": 1,
8  "tabGroups": [
9    { "id": "guides", "label": "Guides", "icon": "book-open" },
10    { "id": "reference", "label": "Reference", "icon": "code" }
11  ]
12}

Configuration Reference

label

Type: string (Required)

Display name shown in the product switcher. Pick something short and recognizable.

1{
2  "label": "REST API"
3}

icon

Type: string

Icon shown next to the product name in the dropdown. Uses Lucide icon names.

1{
2  "icon": "cloud"
3}

Some common choices: "box", "code", "terminal", "server", "database", "smartphone".

description

Type: string

A short description of the product. Shown in the product switcher dropdown below the label.

1{
2  "description": "Complete reference for the REST API endpoints"
3}

activeVersion

Type: string

The default version to show when a user navigates to this product. Overrides the global site.activeVersion for this product.

1{
2  "activeVersion": "v2.0.0"
3}

badge

Type: string

Short text shown as a badge next to the product name. Use it to call attention to a product's status.

1{
2  "badge": "Beta"
3}

Common values: "New", "Beta", "Deprecated", "Enterprise".

position

Type: number

Controls the order of products in the dropdown. Lower numbers appear first.

1{
2  "position": 1
3}

tabGroups

Type: TabGroup[]

Override the global tab groups for this product. Each tab group has an id, label, and optional icon.

1{
2  "tabGroups": [
3    { "id": "guides", "label": "Guides", "icon": "book-open" },
4    { "id": "reference", "label": "API Reference", "icon": "code" }
5  ]
6}

Setting an empty array removes tabs for this product:

1{
2  "tabGroups": []
3}

Examples

API Product

1{
2  "label": "REST API",
3  "icon": "cloud",
4  "description": "Endpoints, authentication, and rate limits",
5  "activeVersion": "v3.0.0",
6  "position": 1
7}

SDK Product

1{
2  "label": "JavaScript SDK",
3  "icon": "code",
4  "description": "Client library for Node.js and browsers",
5  "badge": "New",
6  "position": 2,
7  "tabGroups": [
8    { "id": "quickstart", "label": "Quickstart" },
9    { "id": "reference", "label": "Reference", "icon": "book" }
10  ]
11}

CLI Product

1{
2  "label": "CLI Tool",
3  "icon": "terminal",
4  "description": "Command-line interface for automation",
5  "position": 3
6}

Next Steps