{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://nookdocs.com/schema.json",
"title": "NookDocs Configuration",
"description": "Schema for nookdocs.config.json — the single source of truth for a NookDocs project (multi-tenant docs platform). Editing this file in your repo updates the live site after the webhook syncs.",
"type": "object",
"additionalProperties": true,
"required": [
"name"
],
"properties": {
"$schema": {
"type": "string",
"format": "uri",
"description": "JSON Schema URL for IDE autocomplete. Always set to https://nookdocs.com/schema.json."
},
"name": {
"type": "string",
"description": "Project display name (shown in tab title, OG metadata, etc.)."
},
"theme": {
"type": "string",
"description": "Built-in theme slug. Affects shell layout + CSS tokens. Legacy aliases still resolve but are deprecated — maple→larch, classic→cedar, modern→ember, minimal→sage; write the canonical slug.",
"enum": [
"cedar",
"obsidian",
"birch",
"oak",
"cypress",
"ember",
"larch",
"sage",
"slate",
"terminal"
],
"default": "larch"
},
"contentRoot": {
"type": "string",
"description": "Repo folder containing MDX files. Must end with '/'.",
"pattern": "/$",
"default": "docs/"
},
"appearance": {
"type": "object",
"description": "Default color scheme behavior.",
"additionalProperties": false,
"properties": {
"default": {
"type": "string",
"enum": [
"light",
"dark",
"system"
],
"default": "system"
},
"strict": {
"type": "boolean",
"description": "When true, hide the theme toggle (force a single mode).",
"default": false
}
}
},
"colors": {
"type": "object",
"description": "Brand colors + logo.",
"properties": {
"primary": {
"type": "string",
"description": "Primary accent color (hex). Used for buttons, links, focus rings.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"light": {
"type": "string",
"description": "Primary color in light mode.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"dark": {
"type": "string",
"description": "Primary color in dark mode.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"logo": {
"type": "object",
"description": "Logo images. A root-relative path is served from your repo's public/ folder; an absolute URL is used as given (e.g. a CDN).",
"properties": {
"light": {
"type": "string",
"description": "Light-mode logo — a path under public/ (\"/logo/light.svg\") or an absolute URL."
},
"dark": {
"type": "string",
"description": "Dark-mode logo — a path under public/ (\"/logo/dark.svg\") or an absolute URL."
},
"href": {
"type": "string",
"description": "Click target for the logo. Root-relative paths resolve against your docs base, so \"/\" returns to the docs home even on a subpath. Default: \"/\"."
}
}
}
}
},
"background": {
"type": "object",
"description": "Page background colors or CSS gradients.",
"properties": {
"light": {
"type": "string",
"description": "Light mode background. Solid hex or any CSS gradient."
},
"dark": {
"type": "string",
"description": "Dark mode background."
}
}
},
"typography": {
"type": "object",
"description": "Font family overrides.",
"additionalProperties": false,
"properties": {
"fontFamily": {
"type": "string",
"description": "Default sans-serif font family for body text.",
"examples": [
"Inter",
"Geist",
"Roboto",
"Open Sans"
]
},
"headingFont": {
"type": "string",
"description": "Override font for h1-h4 (defaults to fontFamily)."
},
"bodyFont": {
"type": "string",
"description": "Override font for paragraph body (defaults to fontFamily)."
}
}
},
"navbar": {
"type": "object",
"description": "Top navigation bar configuration.",
"properties": {
"links": {
"type": "array",
"description": "External or internal links shown in the navbar.",
"items": {
"type": "object",
"required": [
"label",
"href"
],
"additionalProperties": false,
"properties": {
"label": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
},
"primaryCta": {
"type": "object",
"description": "Highlighted call-to-action button (e.g. 'Sign up', 'Get started').",
"required": [
"label",
"href"
],
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"description": "Button text, e.g. 'Dashboard', 'Sign up'."
},
"href": {
"type": "string",
"description": "Where it goes. Absolute URL for an external app, or a docs path."
},
"style": {
"type": "string",
"enum": [
"solid",
"outline",
"ghost"
],
"default": "solid",
"description": "Shape. 'solid' = filled pill in the theme accent (default). 'outline' = accent border, transparent fill. 'ghost' = text only."
},
"color": {
"type": "string",
"description": "Fill/border colour. Any CSS colour. Omit to follow the theme's accent — override only when the CTA carries a different brand colour than the docs theme."
},
"textColor": {
"type": "string",
"description": "Label colour on a solid button. Omit to follow the theme's accent foreground."
},
"external": {
"type": "boolean",
"description": "Open in a new tab. Defaults to true for http(s) targets, false for docs paths."
}
}
},
"controls": {
"type": "object",
"additionalProperties": false,
"description": "Where the navbar's controls sit and in what order. Each placement overrides the theme, which otherwise decides all of them together — so you can keep the language switcher in the header while moving the appearance toggle to the sidebar.",
"properties": {
"appearance": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar"
],
"default": "auto",
"description": "Light/dark toggle. Where this control sits. 'auto' follows the theme's own preference."
},
"language": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar"
],
"default": "auto",
"description": "Language switcher. Where this control sits. 'auto' follows the theme's own preference."
},
"version": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar"
],
"default": "auto",
"description": "Version switcher. Where this control sits. 'auto' follows the theme's own preference. The sidebar slot only exists on themes whose footer renders controls; elsewhere the control won't render at all."
},
"product": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar"
],
"default": "auto",
"description": "Product switcher. Where this control sits. 'auto' follows the theme's own preference. The sidebar slot only exists on themes whose footer renders controls; elsewhere the control won't render at all."
},
"assistant": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar"
],
"default": "auto",
"description": "The 'Ask AI' button (only when ai.assistant.trigger resolves to 'button'). 'sidebar' gives it a full-width block in the rail; 'header' puts it in the top bar beside the CTA. 'auto' follows the theme."
},
"order": {
"type": "array",
"items": {
"type": "string",
"enum": [
"appearance",
"language",
"version",
"product",
"assistant"
]
},
"description": "Left-to-right order of the controls that end up in the header. Names you leave out keep their default position after the ones listed."
}
}
}
}
},
"legal": {
"type": "object",
"description": "Legal block — copyright + privacy/terms/cookie links rendered in the site footer.",
"additionalProperties": false,
"properties": {
"copyright": {
"type": "string",
"description": "Copyright line. The token {year} expands to the current year. Example: '© {year} Acme, Inc.'"
},
"privacyUrl": {
"type": "string",
"description": "Privacy policy URL — rendered as a footer legal link."
},
"termsUrl": {
"type": "string",
"description": "Terms of service URL."
},
"cookieUrl": {
"type": "string",
"description": "Cookie policy URL."
},
"links": {
"type": "array",
"description": "Extra legal links (imprint, accessibility statement, etc.).",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"label",
"href"
],
"properties": {
"label": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
}
}
},
"footer": {
"type": "object",
"description": "Footer layout + social links.",
"properties": {
"style": {
"type": "string",
"enum": [
"none",
"page",
"columns"
],
"default": "none",
"description": "'none' hides the footer. 'page' renders a single social-icon + copyright row beneath the page content. 'columns' renders a multi-column link grid with the social row below."
},
"logo": {
"type": "boolean",
"description": "Show the docs' own logo (colors.logo) in the footer. Reuses the navbar logo — no separate path."
},
"social": {
"type": "object",
"description": "Social profile URLs, rendered as brand icons in the page footer. Each key is a platform slug; the value is the profile/page URL.",
"additionalProperties": {
"type": "string",
"format": "uri"
},
"properties": {
"github": {
"type": "string",
"format": "uri"
},
"x": {
"type": "string",
"format": "uri",
"description": "X / Twitter profile URL"
},
"linkedin": {
"type": "string",
"format": "uri"
},
"discord": {
"type": "string",
"format": "uri"
},
"youtube": {
"type": "string",
"format": "uri"
},
"facebook": {
"type": "string",
"format": "uri"
},
"website": {
"type": "string",
"format": "uri"
},
"slack": {
"type": "string",
"format": "uri"
},
"instagram": {
"type": "string",
"format": "uri"
},
"hackernews": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"telegram": {
"type": "string",
"format": "uri"
},
"bluesky": {
"type": "string",
"format": "uri"
},
"threads": {
"type": "string",
"format": "uri"
},
"reddit": {
"type": "string",
"format": "uri"
},
"podcast": {
"type": "string",
"format": "uri"
}
}
},
"links": {
"type": "array",
"description": "Column definitions for the 'columns' footer style. Each column has a title and an array of { label, href } links.",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
}
}
}
},
"width": {
"type": "string",
"enum": [
"reading",
"content",
"full"
],
"description": "How wide the footer's surface runs — independent of footer.style, so it applies to page and columns footers alike. 'reading' (the default) aligns it with the reading column — the same narrow width as the page text and the 'Was this helpful?' feedback block. 'content' widens it to the outer content column (article + TOC width). 'full' spans the whole viewport and the sidebar stops at the footer's top rule. Omit to follow the active theme, then the 'reading' default."
}
}
},
"seo": {
"type": "object",
"description": "SEO defaults applied to all pages. Per-page frontmatter overrides these.",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Default site title. Page titles render as '{page} | {title}'."
},
"description": {
"type": "string",
"description": "Default meta description when a page has none."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Default meta keywords for the site. Per-page frontmatter 'keywords' overrides."
},
"author": {
"type": "string",
"description": "Default content author — emitted as ."
},
"ogImage": {
"type": "string",
"description": "Default Open Graph / social preview image URL."
},
"favicon": {
"type": "string",
"description": "Favicon URL (path under your repo's public/ folder)."
},
"indexing": {
"type": "string",
"enum": [
"default",
"noindex"
],
"description": "Set to 'noindex' to hide entire site from search engines.",
"default": "default"
},
"metatags": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Free-form tag map, keyed by meta-name (e.g. 'twitter:site'). Appended to every page."
}
}
},
"geo": {
"type": "object",
"description": "GEO / AEO — generative & answer engine optimization. JSON-LD structured data, AI-crawler control, and citation signals for AI Overviews / Perplexity / ChatGPT.",
"additionalProperties": false,
"properties": {
"structuredData": {
"type": "boolean",
"default": true,
"description": "Emit JSON-LD (TechArticle, BreadcrumbList, Organization, WebSite) on every page."
},
"faqSchema": {
"type": "boolean",
"default": true,
"description": "Emit FAQPage JSON-LD from a page's frontmatter `faq: [{ q, a }]`."
},
"organization": {
"type": "object",
"additionalProperties": false,
"description": "Publisher entity used in the JSON-LD graph.",
"properties": {
"name": {
"type": "string"
},
"logo": {
"type": "string",
"description": "Logo URL (absolute or repo-relative)."
},
"sameAs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Profile URLs identifying the same entity (X, GitHub, LinkedIn, Wikipedia…)."
}
}
},
"aiCrawlers": {
"description": "AI crawler access in robots.txt. 'allow' (default) or 'block' all AI bots, or a per-bot map keyed by user-agent (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, …).",
"oneOf": [
{
"type": "string",
"enum": [
"allow",
"block"
]
},
{
"type": "object",
"additionalProperties": {
"type": "boolean"
}
}
]
},
"llmsTxt": {
"type": "object",
"additionalProperties": false,
"description": "Extra context lines for the auto-generated /llms.txt.",
"properties": {
"intro": {
"type": "string"
},
"contact": {
"type": "string"
}
}
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Primary topics/entities the site covers — surfaced as JSON-LD `about`."
},
"audience": {
"type": "string",
"description": "Target audience, e.g. 'developers'."
},
"license": {
"type": "string",
"description": "Content reuse / citation license, e.g. 'CC-BY-4.0'."
}
}
},
"customCss": {
"type": "string",
"description": "Per-tenant custom CSS. Appended to the docs site head and cascades over every theme + typography rule. Pro+ feature — Free tier saves are rejected server-side."
},
"branding": {
"type": "object",
"description": "White-labeling controls. Setting branding.poweredBy: false requires the Team plan or higher.",
"additionalProperties": false,
"properties": {
"poweredBy": {
"type": "boolean",
"default": true,
"description": "Show the \"Powered by NookDocs\" attribution in the page footer. Default true. Set to false to hide it (Team+ only)."
}
}
},
"advanced": {
"type": "object",
"description": "Niche behaviors that don't fit elsewhere.",
"additionalProperties": false,
"properties": {
"notFound": {
"type": "object",
"description": "Custom 404 page configuration.",
"properties": {
"active": {
"type": "boolean",
"default": false
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"drilldownNavigation": {
"type": "boolean",
"deprecated": true,
"description": "Deprecated — use `interaction.drilldown` instead. Read only when `interaction.drilldown` is absent, so setting both means this one does nothing. Note the defaults differ: this defaulted to false, `interaction.drilldown` defaults to true.",
"default": false
},
"showTimestamp": {
"type": "boolean",
"description": "Show 'Last updated' timestamp at the bottom of each page.",
"default": true
}
}
},
"navigation": {
"description": "Site navigation hierarchy. Either a flat array (V1) or a structured object (V2).",
"oneOf": [
{
"type": "array",
"description": "V1: array of tab/group entries.",
"items": {
"$ref": "#/$defs/NavigationEntry"
}
},
{
"type": "object",
"description": "V2: structured navigation with anchors/dropdowns/products/versions/languages support.",
"additionalProperties": false,
"properties": {
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
},
"tabs": {
"type": "array",
"items": {
"$ref": "#/$defs/Tab"
}
},
"anchors": {
"type": "array",
"items": {
"$ref": "#/$defs/Anchor"
}
},
"dropdowns": {
"type": "array",
"items": {
"$ref": "#/$defs/Dropdown"
}
},
"products": {
"type": "array",
"items": {
"$ref": "#/$defs/Product"
}
},
"versions": {
"type": "array",
"items": {
"$ref": "#/$defs/Version"
}
},
"languages": {
"type": "array",
"items": {
"$ref": "#/$defs/Language"
}
},
"global": {
"type": "object",
"description": "Items shown across all versions/languages.",
"properties": {
"anchors": {
"type": "array",
"items": {
"$ref": "#/$defs/Anchor"
}
}
}
}
}
}
]
},
"api": {
"type": "object",
"description": "OpenAPI / API reference settings.",
"properties": {
"baseUrl": {
"type": "string",
"format": "uri"
},
"openapi": {
"type": "string",
"description": "Path to OpenAPI spec (relative to repo root) OR full URL."
},
"asyncapi": {
"type": "string",
"description": "Path or URL to AsyncAPI spec (planned)."
},
"playground": {
"description": "Try-It playground. `\"interactive\"` (or `true`) runs live requests; `\"simple\"` shows the form without sending; `\"none\"` (or `false`) hides it.",
"default": "interactive",
"oneOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": [
"interactive",
"simple",
"none"
]
}
]
},
"auth": {
"type": "object",
"description": "Default auth scheme for the playground.",
"properties": {
"name": {
"type": "string",
"examples": [
"API Key",
"Bearer Token"
]
},
"type": {
"type": "string",
"enum": [
"bearer",
"basic",
"apiKey",
"oauth2"
]
}
}
}
}
},
"brand": {
"type": "object",
"description": "Pluggable brand asset system (logos, OG images, favicons, manifest).",
"additionalProperties": true
},
"versions": {
"type": "array",
"description": "Phase 3+ version switcher. Each entry defines a docs version; the navbar shows a dropdown to switch between them. Exactly one entry may have `default: true`.",
"items": {
"$ref": "#/$defs/Version"
}
},
"languages": {
"type": "array",
"description": "Phase 3+ language switcher. Each entry defines a locale; the navbar shows a dropdown to switch between them. Exactly one entry may have `default: true`.",
"items": {
"$ref": "#/$defs/Language"
}
},
"products": {
"type": "array",
"description": "Phase 3+ multi-product switcher. Renders a dropdown near the logo to switch between products.",
"items": {
"$ref": "#/$defs/Product"
}
},
"global": {
"type": "object",
"description": "Phase 3+ global chrome that persists across product / version / language switches.",
"additionalProperties": false,
"properties": {
"anchors": {
"type": "array",
"items": {
"$ref": "#/$defs/Anchor"
}
},
"dropdowns": {
"type": "array",
"items": {
"$ref": "#/$defs/Dropdown"
}
},
"notFound": {
"type": "object",
"properties": {
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
}
}
}
}
},
"redirects": {
"type": "array",
"description": "URL redirects applied at the docs page layer. Tenants add entries to map old paths to new ones during migrations or rename flows.",
"items": {
"type": "object",
"required": [
"source",
"destination"
],
"properties": {
"source": {
"type": "string",
"description": "Source path. Trailing '/*' enables prefix matching; the matched tail is preserved when the destination also ends in '/*'."
},
"destination": {
"type": "string",
"description": "Destination path or absolute URL."
},
"permanent": {
"type": "boolean",
"default": false,
"description": "When true, returns HTTP 308 (permanent). Otherwise 307 (temporary). Search engines respect 308 and transfer ranking signals to the new URL."
}
}
}
},
"interaction": {
"type": "object",
"description": "Navigation interaction toggles. Affects how group/tab clicks behave.",
"additionalProperties": false,
"properties": {
"drilldown": {
"type": "boolean",
"description": "Controls Group.root click behaviour. When true (default), clicking a group label with `root` set navigates to that page. When false, clicking only toggles expand/collapse.",
"default": true
}
}
},
"ai": {
"type": "object",
"description": "AI features (assistant, future agent).",
"additionalProperties": false,
"properties": {
"assistant": {
"type": "object",
"description": "On-site AI chat widget for your docs — answers from your content.",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean",
"description": "Show the assistant on every docs page. Default false (opt-in).",
"default": false
},
"trigger": {
"type": "string",
"enum": [
"button",
"bar",
"input"
],
"description": "How readers open the assistant. 'button' = a button in the header (after search). 'bar' = a floating pill centered at the bottom of the content. 'input' = a docked input pill in the bottom-right. All open the same conversation drawer. Omit to follow the active theme's own preference (themes that express none fall back to 'button')."
},
"label": {
"type": "string",
"default": "Ask AI",
"description": "Text shown on the trigger (button label / input placeholder) and as the drawer title. Default 'Ask AI'. Override to match your brand voice (e.g. 'Ask Acme', 'Docs AI')."
},
"provider": {
"type": "string",
"enum": [
"openai",
"anthropic",
"openrouter"
],
"description": "AI provider for `model` — only used with Bring-Your-Own-Key. Set it to the provider whose API key you added under AI models (BYOK): `openai`, `anthropic`, or your own `openrouter` account. Without a BYOK key, the assistant uses the AI included in your plan and this field is ignored."
},
"model": {
"type": "string",
"description": "Model identifier for the chosen `provider` (e.g. 'gpt-4o' for openai, 'claude-3-5-sonnet-latest' for anthropic, 'anthropic/claude-3.5-sonnet' for openrouter). Only honored when a matching BYOK key is set.",
"examples": [
"gpt-4o",
"claude-3-5-sonnet-latest",
"anthropic/claude-3.5-sonnet"
]
},
"systemPrompt": {
"type": "string",
"description": "Override the default system prompt. Use this to constrain tone, persona, or scope."
}
}
}
}
},
"feedback": {
"type": "object",
"description": "Per-page 'Was this page helpful?' widget at the bottom of every docs page. Default: enabled with Mintlify-style reason options.",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Toggle the widget per tenant."
},
"prompt": {
"type": "string",
"description": "Override the top prompt. Default: 'Was this page helpful?'."
},
"positiveReasons": {
"type": "array",
"description": "Radio options shown after Yes. Falls back to a sensible default set when omitted.",
"items": {
"type": "object",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string",
"description": "Stable key written to page_feedback.reason."
},
"label": {
"type": "string",
"description": "Shown in the radio list."
}
}
}
},
"negativeReasons": {
"type": "array",
"description": "Radio options shown after No.",
"items": {
"type": "object",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
},
"github": {
"type": "object",
"description": "GitHub issue automation for negative feedback.",
"properties": {
"autoIssue": {
"type": "boolean",
"default": false,
"description": "Open a GitHub issue when a thumbs-down includes a comment."
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"docs-feedback"
],
"description": "Labels attached to auto-opened issues."
}
}
}
}
},
"analytics": {
"type": "object",
"description": "First-party analytics beacon + dashboard. Records views, searches, feedback, and assistant usage into the platform's own tables. Independent of integrations.* (GA4/PostHog/Plausible/...).",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Enable the beacon. Turn off to disable all first-party analytics capture for this tenant."
}
}
},
"contextual": {
"type": "object",
"description": "Configures the contextual menu shown next to page titles (Copy page, Open in ChatGPT, etc.).",
"properties": {
"enabled": {
"type": "array",
"description": "Built-in sections to show. Omit to show all. Unknown values are ignored.",
"items": {
"type": "string",
"enum": [
"content",
"ai-platforms",
"mcp",
"custom"
]
}
},
"display": {
"type": "string",
"enum": [
"header",
"toc"
],
"default": "header",
"description": "Where to render the menu. 'toc' placement is queued for a follow-up release."
},
"options": {
"type": "array",
"description": "Tenant-defined custom menu items. Each appears in the 'Custom' section of the dropdown.",
"items": {
"type": "object",
"required": [
"title",
"href"
],
"properties": {
"title": {
"type": "string",
"description": "Menu item label."
},
"description": {
"type": "string",
"description": "Subtitle shown under the title."
},
"icon": {
"type": "string",
"description": "Lucide icon name or absolute image URL."
},
"href": {
"type": "string",
"description": "Target URL. Supports template variables resolved at click time: $page (full URL), $path (pathname), $title (page title), $mdx (URL-encoded MDX source)."
}
}
}
},
"platforms": {
"type": "array",
"items": {
"type": "string",
"enum": [
"chatgpt",
"claude",
"perplexity",
"aistudio",
"grok",
"windsurf"
]
},
"description": "Which AI platforms appear in the 'AI platforms' section. Omit and ChatGPT and Claude are shown — a menu listing seven destinations makes the reader read a list instead of clicking the one they wanted. Name the ones you want to offer to change that. Ignored when 'enabled' leaves 'ai-platforms' out."
}
}
},
"sidebar": {
"type": "object",
"additionalProperties": false,
"description": "Sidebar appearance overrides. Every key defaults to 'auto', meaning the theme decides — set one only when you want to depart from the theme you picked.",
"properties": {
"activeStyle": {
"type": "string",
"enum": [
"auto",
"bg-tint",
"text-only",
"text-tint",
"caret"
],
"default": "auto",
"description": "How the current page is marked. 'bg-tint' fills a pill behind it; 'text-only' draws a rail down every row with an accent bar on the active one; 'text-tint' colours the label and paints nothing else; 'caret' puts a chevron in the margin beside the active page and draws no rail. 'auto' follows the theme."
},
"showIcons": {
"type": "string",
"enum": [
"auto",
"true",
"false"
],
"default": "auto",
"description": "Show per-page icons in the sidebar. 'auto' follows the theme."
},
"scrollbar": {
"type": "string",
"enum": [
"auto",
"always",
"hover"
],
"default": "auto",
"description": "Whether the sidebar scrollbar is always visible or appears on hover. 'auto' follows the theme. Touch devices never show one either way."
},
"groupLabelStyle": {
"type": "string",
"enum": [
"auto",
"normal",
"uppercase",
"uppercase-mono"
],
"default": "auto",
"description": "Casing and weight of group headings. 'auto' follows the theme."
},
"collapsibleGroups": {
"type": "string",
"enum": [
"auto",
"true",
"false"
],
"default": "auto",
"description": "Whether sidebar groups get a chevron toggle. 'auto' follows the theme."
},
"defaultGroupState": {
"type": "string",
"enum": [
"auto",
"expanded",
"collapsed"
],
"default": "auto",
"description": "How collapsible groups start: 'expanded' opens all of them, 'collapsed' opens only the group holding the current page. Ignored when groups aren't collapsible. Per-group 'expanded' in navigation still wins."
}
}
},
"codeBlockStyle": {
"type": "string",
"enum": [
"auto",
"card",
"inset",
"terminal"
],
"default": "auto",
"description": "How fenced code blocks are framed. 'card' is a bordered block with a header strip; 'inset' drops the border for a raised surface with the code recessed in a darker well; 'terminal' keeps sharp corners and a prompt marker before the language. 'auto' follows the theme."
},
"layout": {
"type": "object",
"additionalProperties": false,
"description": "Where the navigation chrome sits. Each theme picks its own arrangement; these depart from it without leaving the theme. 'auto' (or omitting a key) keeps the theme's choice.",
"properties": {
"shell": {
"type": "string",
"enum": [
"auto",
"header-sidebar",
"sidebar-first",
"header-only"
],
"default": "auto",
"description": "Which shell frames the page. 'header-sidebar' is a header bar above a sidebar, 'sidebar-first' drops the header so the rail owns the full height, 'header-only' has no rail. The largest of these overrides — it swaps the whole frame."
},
"tabPosition": {
"type": "string",
"enum": [
"auto",
"header",
"sidebar-list",
"sidebar-dropdown"
],
"default": "auto",
"description": "Where navigation tabs render — across the header, or down the sidebar as a list or a dropdown."
},
"headerRows": {
"type": "string",
"enum": [
"auto",
"0",
"1",
"2"
],
"default": "auto",
"description": "Header rows. '0' drops the header bar entirely, '1' keeps tabs on the logo row, '2' gives them their own strip beneath it."
},
"tabStyle": {
"type": "string",
"enum": [
"auto",
"underline",
"pill",
"text",
"text-right"
],
"default": "auto",
"description": "How header tabs are drawn."
},
"tabAlign": {
"type": "string",
"enum": [
"auto",
"start",
"center",
"end"
],
"default": "auto",
"description": "Horizontal placement of single-row tabs. Ignored when headerRows is 2."
}
}
},
"viewSwitcherStyle": {
"type": "string",
"enum": [
"auto",
"dropdown",
"tabs"
],
"default": "auto",
"description": "How the page-level View switcher is drawn. 'dropdown' (the default) states the current choice in one line and stays one control however many variants a page offers; 'tabs' spreads them in a row, which reads well for two or three and wraps past that."
},
"banner": {
"type": "object",
"description": "Site-wide announcement banner rendered above the navbar.",
"required": [
"content"
],
"additionalProperties": false,
"properties": {
"content": {
"type": "string",
"description": "Banner text (inline Markdown supported)."
},
"dismissible": {
"type": "boolean",
"description": "Let readers dismiss the banner (remembered per browser)."
},
"variant": {
"type": "string",
"enum": [
"info",
"warning",
"primary"
],
"description": "Visual tone. Default: info."
}
}
},
"search": {
"type": "object",
"description": "Search UI options.",
"additionalProperties": false,
"properties": {
"prompt": {
"type": "string",
"description": "Placeholder text shown in the search input."
}
}
},
"integrations": {
"type": "object",
"description": "Third-party analytics / chat integrations. Each provider takes its own small config object; see the integrations guide for per-provider fields.",
"additionalProperties": false,
"properties": {
"osano": {
"type": "object",
"description": "osano integration settings."
},
"intercom": {
"type": "object",
"description": "intercom integration settings."
},
"frontChat": {
"type": "object",
"description": "frontChat integration settings."
},
"ga4": {
"type": "object",
"description": "ga4 integration settings."
},
"gtm": {
"type": "object",
"description": "gtm integration settings."
},
"posthog": {
"type": "object",
"description": "posthog integration settings."
},
"plausible": {
"type": "object",
"description": "plausible integration settings."
},
"fathom": {
"type": "object",
"description": "fathom integration settings."
},
"mixpanel": {
"type": "object",
"description": "mixpanel integration settings."
},
"segment": {
"type": "object",
"description": "segment integration settings."
},
"amplitude": {
"type": "object",
"description": "amplitude integration settings."
},
"clarity": {
"type": "object",
"description": "clarity integration settings."
},
"hotjar": {
"type": "object",
"description": "hotjar integration settings."
},
"logrocket": {
"type": "object",
"description": "logrocket integration settings."
},
"pirsch": {
"type": "object",
"description": "pirsch integration settings."
},
"heap": {
"type": "object",
"description": "heap integration settings."
},
"truestat": {
"description": "TrueStat analytics. The site key on its own, or `{ siteKey, domain }` when the docs host differs from the property being tracked.",
"oneOf": [
{
"type": "string",
"description": "Site key, e.g. `ts_cd067fec0d8b204f35f1`."
},
{
"type": "object",
"properties": {
"siteKey": {
"type": "string",
"description": "Site key from the install page."
},
"domain": {
"type": "string",
"description": "Property to report against. Defaults to the site's own domain."
}
}
}
]
}
}
},
"icons": {
"type": "object",
"description": "Icon rendering options.",
"additionalProperties": false,
"properties": {
"library": {
"type": "string",
"enum": [
"lucide",
"tabler",
"fontawesome"
],
"description": "Preferred library for icon name resolution. Names fall back Lucide → Tabler → Font Awesome. Default: lucide."
}
}
},
"metadata": {
"type": "object",
"description": "Arbitrary key→value metadata attached to the site (exposed to templates and exports).",
"additionalProperties": {
"type": "string"
}
}
},
"$defs": {
"PageRef": {
"description": "A page reference. Accepts a string path, a PageObject with per-entry overrides, or an ExternalLink.",
"oneOf": [
{
"type": "string",
"description": "Path to MDX file (without extension), e.g. 'docs/quickstart'."
},
{
"type": "object",
"required": [
"page"
],
"description": "PageObject — adds per-entry overrides without touching frontmatter.",
"properties": {
"page": {
"type": "string"
},
"label": {
"type": "string",
"description": "Override the frontmatter title in this nav appearance."
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
],
"description": "Icon style (FontAwesome only; ignored for Lucide)."
},
"tag": {
"type": "string",
"description": "Badge text like 'NEW' or 'BETA'."
},
"hidden": {
"type": "boolean"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "Auth gating: user must belong to at least one of these group slugs."
},
"public": {
"type": "boolean",
"description": "Force public visibility even when parent is auth-gated."
}
}
},
{
"type": "object",
"required": [
"href",
"label"
],
"description": "ExternalLink — renders as a sidebar item that opens in a new tab.",
"properties": {
"href": {
"type": "string",
"description": "Absolute URL for an external link, or a root-relative path like \"/quickstart\" for one of your own pages. A root-relative href opens in the same tab with no outbound arrow."
},
"label": {
"type": "string"
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
]
},
"tag": {
"type": "string"
},
"hidden": {
"type": "boolean"
}
}
}
]
},
"NavigationEntry": {
"description": "Top-level navigation entry. Phase 2 accepted Tab / Group; Phase 3 adds Anchor and Dropdown so they can sit at the root of `navigation` above the groups.",
"oneOf": [
{
"$ref": "#/$defs/Tab"
},
{
"$ref": "#/$defs/Group"
},
{
"$ref": "#/$defs/Anchor"
},
{
"$ref": "#/$defs/Dropdown"
}
]
},
"Group": {
"type": "object",
"description": "A collapsible section in the sidebar.",
"required": [
"group"
],
"properties": {
"group": {
"type": "string",
"description": "Group label shown in sidebar."
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
]
},
"tag": {
"type": "string",
"description": "Badge text like 'NEW'. Renders as a small pill next to the group label."
},
"root": {
"$ref": "#/$defs/PageRef",
"description": "Page rendered when the group title is clicked (requires interaction.drilldown)."
},
"directory": {
"type": "string",
"enum": [
"none",
"accordion",
"card"
],
"description": "Auto-render child links on the root page in this layout."
},
"expanded": {
"type": "boolean",
"description": "Default expanded state. Honoured explicitly; omit to use active-page heuristic."
},
"collapsible": {
"type": "boolean",
"description": "Render this group with a chevron toggle even when the theme keeps groups expanded. Per-group override of the theme's collapsibleGroups setting."
},
"hidden": {
"type": "boolean",
"description": "Hide this group from the sidebar. Child pages remain URL-accessible."
},
"authGroups": {
"type": "array",
"items": {
"type": "string"
},
"description": "Auth gating: user must belong to at least one of these group slugs. Requires auth provider."
},
"public": {
"type": "boolean",
"description": "Force public visibility even when parent is auth-gated."
},
"openapi": {
"description": "Auto-generate pages from an OpenAPI spec for this group.",
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/OpenAPIBinding"
}
]
},
"asyncapi": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/OpenAPIBinding"
}
]
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/PageRef"
},
{
"$ref": "#/$defs/Group"
}
]
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
}
}
},
"OpenAPIBinding": {
"type": "object",
"required": [
"source"
],
"description": "Explicit OpenAPI binding (file/URL + optional tag filter).",
"properties": {
"source": {
"type": "string",
"description": "File path or URL."
},
"directory": {
"type": "string",
"description": "Generated MDX path prefix."
},
"filter": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeTags": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"Tab": {
"type": "object",
"description": "A top-level horizontal tab in the navbar.",
"required": [
"tab"
],
"properties": {
"tab": {
"type": "string"
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
]
},
"tag": {
"type": "string",
"description": "Badge text next to the tab label."
},
"href": {
"type": "string",
"description": "External link — when set, the tab is a link (no sidebar) and opens in a new tab."
},
"hidden": {
"type": "boolean",
"description": "Hide this tab from the navbar. Its pages remain URL-accessible."
},
"openapi": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/OpenAPIBinding"
}
]
},
"asyncapi": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/OpenAPIBinding"
}
]
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
},
"menus": {
"type": "array",
"items": {
"$ref": "#/$defs/Menu"
}
},
"anchors": {
"type": "array",
"description": "Per-tab anchors — render above groups inside this tab's sidebar.",
"items": {
"$ref": "#/$defs/Anchor"
}
},
"dropdowns": {
"type": "array",
"description": "Per-tab dropdowns — render above groups inside this tab's sidebar.",
"items": {
"$ref": "#/$defs/Dropdown"
}
}
}
},
"Anchor": {
"type": "object",
"description": "A persistent sidebar item, often used for community/changelog/external links. With `href` it's a plain link; with `pages`/`groups` it's an inline-expandable section.",
"required": [
"anchor"
],
"properties": {
"anchor": {
"type": "string",
"description": "Label shown in the sidebar."
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
]
},
"tag": {
"type": "string",
"description": "Badge text like 'NEW'."
},
"hidden": {
"type": "boolean"
},
"href": {
"type": "string",
"description": "Where the anchor goes. Absolute URL for an external link, or a root-relative path like \"/changelog\" for one of your own pages. Mutually exclusive with pages/groups."
},
"target": {
"type": "string",
"enum": [
"_self",
"_blank"
],
"description": "Link target. Defaults to _blank for external URLs."
},
"expanded": {
"type": "boolean",
"default": false,
"description": "Initial open state when the anchor has children."
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
}
}
},
"Dropdown": {
"type": "object",
"description": "An expandable top-of-sidebar menu. Always has children (pages and/or groups); unlike anchors, dropdowns cannot be plain links.",
"required": [
"dropdown"
],
"properties": {
"dropdown": {
"type": "string"
},
"icon": {
"type": "string"
},
"iconType": {
"type": "string",
"enum": [
"regular",
"solid",
"light",
"thin",
"sharp-solid",
"duotone",
"brands"
]
},
"tag": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"description": {
"type": "string"
},
"expanded": {
"type": "boolean",
"default": false,
"description": "Initial open state. Persists in localStorage once the user toggles."
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
}
}
},
"Menu": {
"type": "object",
"description": "A dropdown sub-nav inside a tab. Item = label, description = sub-text.",
"required": [
"item"
],
"properties": {
"item": {
"type": "string"
},
"description": {
"type": "string"
},
"icon": {
"type": "string"
},
"href": {
"type": "string"
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
}
}
},
"Product": {
"type": "object",
"description": "A top-level product divider (multi-product navigation).",
"required": [
"product"
],
"properties": {
"product": {
"type": "string"
},
"icon": {
"type": "string"
},
"description": {
"type": "string"
},
"href": {
"type": "string"
},
"tabs": {
"type": "array",
"items": {
"$ref": "#/$defs/Tab"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"label": {
"type": "string",
"description": "Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show \"English\" instead of \"en\"."
},
"slug": {
"type": "string",
"description": "URL segment for this entry. Defaults to a slug of the label."
},
"hidden": {
"type": "boolean",
"description": "Keep the entry out of the switcher while its pages stay reachable."
},
"tag": {
"type": "string",
"description": "Small badge shown beside the entry (e.g. NEW, BETA)."
},
"status": {
"type": "string",
"enum": [
"stable",
"beta",
"deprecated",
"preview"
],
"description": "Status badge shown beside the entry."
}
}
},
"Version": {
"type": "object",
"description": "A version selector entry.",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"description": "Version label, e.g. 'v2', '2024-10'."
},
"default": {
"type": "boolean",
"description": "Mark as the default version (latest)."
},
"tag": {
"type": "string",
"description": "Badge like 'Latest' or 'Deprecated'."
},
"tabs": {
"type": "array",
"items": {
"$ref": "#/$defs/Tab"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"label": {
"type": "string",
"description": "Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show \"English\" instead of \"en\"."
},
"slug": {
"type": "string",
"description": "URL segment for this entry. Defaults to a slug of the label."
},
"hidden": {
"type": "boolean",
"description": "Keep the entry out of the switcher while its pages stay reachable."
},
"status": {
"type": "string",
"enum": [
"stable",
"beta",
"deprecated",
"preview"
],
"description": "Status badge shown beside the entry."
}
}
},
"Language": {
"type": "object",
"description": "A language selector entry. Per-language overrides for navbar/footer/banner.",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"description": "ISO 639-1 code (en, tr, de, es, fr, ja, zh, ar, etc.)."
},
"default": {
"type": "boolean"
},
"navbar": {
"$ref": "#/properties/navbar"
},
"footer": {
"$ref": "#/properties/footer"
},
"tabs": {
"type": "array",
"items": {
"$ref": "#/$defs/Tab"
}
},
"groups": {
"type": "array",
"items": {
"$ref": "#/$defs/Group"
}
},
"pages": {
"type": "array",
"items": {
"$ref": "#/$defs/PageRef"
}
},
"label": {
"type": "string",
"description": "Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show \"English\" instead of \"en\"."
},
"slug": {
"type": "string",
"description": "URL segment for this entry. Defaults to a slug of the label."
},
"hidden": {
"type": "boolean",
"description": "Keep the entry out of the switcher while its pages stay reachable."
},
"tag": {
"type": "string",
"description": "Small badge shown beside the entry (e.g. NEW, BETA)."
},
"status": {
"type": "string",
"enum": [
"stable",
"beta",
"deprecated",
"preview"
],
"description": "Status badge shown beside the entry."
}
}
}
}
}