Version Configuration
Configure per-version settings with _version_.json
Version Configuration
Each version of your documentation can have its own _version_.json file to customize how that version appears and behaves. All fields are optional — only add what you need.
Place the file at the root of a version folder:
1docs/2├── v1.0.0/3│ ├── _version_.json ← version config4│ └── getting-started.en.mdx5├── v2.0.0/6│ ├── _version_.json7│ └── getting-started.en.mdxIn multi-product setups, it goes inside the product's version folder:
1docs/2├── api/3│ ├── v1.0.0/4│ │ └── _version_.json5│ └── v2.0.0/6│ └── _version_.jsonBasic Configuration
A simple _version_.json:
1{2 "label": "v1.0 (Stable)"3}This gives the version a friendly display name instead of showing the raw directory name.
Complete Example
A fully configured version:
1{2 "label": "v2.0 Beta",3 "hidden": false,4 "badge": "Beta",5 "banner": {6 "text": "This version is in beta. Some features may change before release.",7 "type": "warning"8 },9 "tabGroups": [10 { "id": "guides", "label": "Guides", "icon": "book-open" },11 { "id": "reference", "label": "Reference", "icon": "code" }12 ]13}Configuration Reference
label
Type: string
Default: Directory name (e.g., "v1.0.0")
Display name shown in the version switcher. Useful for adding context like stability status.
1{2 "label": "v1.0 (Stable)"3}Other examples: "v2.0 Beta", "v3.0 LTS", "v0.9 Legacy".
hidden
Type: boolean
Default: false
Hides this version from the version switcher dropdown. The pages still exist and are accessible by URL — they just won't appear in the dropdown.
1{2 "hidden": true3}badge
Type: string
Short text shown as a badge next to the version in the switcher. Helps users quickly identify version status.
1{2 "badge": "LTS"3}Common values: "Beta", "LTS", "Stable", "Deprecated", "Preview".
banner
Type: object
A banner shown at the top of every page in this version. Useful for warnings about deprecated or pre-release versions. Overrides any global banner set in specra.config.json.
1{2 "banner": {3 "text": "This version is deprecated. Please upgrade to [v2.0](/docs/v2.0.0/getting-started).",4 "type": "warning"5 }6}Banner fields:
| Field | Type | Default | Description |
|---|---|---|---|
text | string | — | The banner message. Supports markdown links like [text](/url). |
type | string | "info" | Banner style: "info", "warning", "error", or "success". |
tabGroups
Type: TabGroup[]
Override tab groups for this specific version. Each tab group has an id, label, and optional icon (Lucide icon name).
1{2 "tabGroups": [3 { "id": "guides", "label": "Guides", "icon": "book-open" },4 { "id": "api", "label": "API Docs", "icon": "code" }5 ]6}Setting an empty array removes tabs for this version:
1{2 "tabGroups": []3}Version-level tab groups override both the global config and any product-level tab groups. This is the most specific level of the override chain: global → product → version.
Common Patterns
Marking a Version as Deprecated
1{2 "label": "v1.0 (Deprecated)",3 "badge": "Deprecated",4 "banner": {5 "text": "This version is no longer maintained. Please migrate to [v2.0](/docs/v2.0.0/getting-started).",6 "type": "error"7 }8}Beta or Preview Version
1{2 "label": "v3.0 Preview",3 "badge": "Preview",4 "banner": {5 "text": "This is a preview release. APIs may change before the stable release.",6 "type": "warning"7 }8}Long-Term Support Version
1{2 "label": "v2.0 LTS",3 "badge": "LTS",4 "banner": {5 "text": "Long-term support — this version receives security patches until 2027.",6 "type": "success"7 }8}Hiding an Unreleased Version
1{2 "label": "v4.0 (Unreleased)",3 "hidden": true,4 "badge": "Dev",5 "banner": {6 "text": "This version is under active development and not yet released.",7 "type": "info"8 }9}