> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# docs.json schema reference
> Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site.
Required fields have a required badge. All other fields are optional.
For context on what each group of settings does, see the topic pages:
* [Appearance and branding](/organize/settings-appearance)
* [Site structure](/organize/settings-structure)
* [API settings](/organize/settings-api)
* [Integrations](/organize/settings-integrations)
* [SEO and search](/organize/settings-seo)
## Quick reference
| Property | Type | Required | Default |
| ---------------------------- | ----------------------------------------------------- | -------- | --------------- |
| `$ref` | string (file path) | No | None |
| `theme` | string | Yes | None |
| `name` | string | Yes | None |
| `colors.primary` | string (hex) | Yes | None |
| `navigation` | object | Yes | None |
| `description` | string | No | None |
| `logo` | string or object | No | None |
| `favicon` | string or object | No | None |
| `appearance.default` | `"system"` \| `"light"` \| `"dark"` | No | `"system"` |
| `appearance.strict` | boolean | No | `false` |
| `fonts.family` | string | No | Theme default |
| `icons.library` | `"fontawesome"` \| `"lucide"` \| `"tabler"` | No | `"fontawesome"` |
| `background.decoration` | `"gradient"` \| `"grid"` \| `"windows"` | No | None |
| `styling.eyebrows` | `"section"` \| `"breadcrumbs"` | No | `"section"` |
| `styling.latex` | boolean | No | Auto-detected |
| `styling.codeblocks` | `"system"` \| `"dark"` \| string \| object | No | `"system"` |
| `thumbnails.appearance` | `"light"` \| `"dark"` | No | Site default |
| `navbar.links` | array | No | None |
| `navbar.primary` | object | No | None |
| `footer.socials` | object | No | None |
| `footer.links` | array | No | None |
| `banner.content` | string | No | None |
| `banner.dismissible` | boolean | No | `false` |
| `banner.type` | `"info"` \| `"warning"` \| `"critical"` | No | `"info"` |
| `banner.color` | object \| string | No | None |
| `interaction.drilldown` | boolean | No | Theme default |
| `contextual.options` | array | No | None |
| `contextual.display` | `"header"` \| `"toc"` | No | `"header"` |
| `redirects` | array | No | None |
| `variables` | object | No | None |
| `metadata.timestamp` | boolean | No | `false` |
| `errors.404.redirect` | boolean | No | `true` |
| `errors.404.title` | string | No | None |
| `errors.404.description` | string | No | None |
| `api.openapi` | string or array or object | No | None |
| `api.asyncapi` | string or array or object | No | None |
| `api.playground.display` | `"interactive"` \| `"simple"` \| `"none"` \| `"auth"` | No | `"interactive"` |
| `api.playground.proxy` | boolean | No | `true` |
| `api.playground.credentials` | boolean | No | `false` |
| `api.params.expanded` | `"all"` \| `"closed"` | No | `"closed"` |
| `api.params.post` | array of string | No | None |
| `api.url` | `"full"` | No | None |
| `api.examples.languages` | array of string | No | None |
| `api.examples.defaults` | `"required"` \| `"all"` | No | `"all"` |
| `api.examples.prefill` | boolean | No | `false` |
| `api.examples.autogenerate` | boolean | No | `true` |
| `seo.indexing` | `"navigable"` \| `"all"` | No | `"navigable"` |
| `seo.metatags` | object | No | None |
| `search.prompt` | string | No | None |
| `integrations.*` | object | No | None |
## Full property reference
### `$ref`
Load configuration from another JSON file. Use `$ref` at any level of your `docs.json` to split configuration across multiple files.
**Type:** string—relative file path to a `.json` file
* When `$ref` resolves to an object, Mintlify merges any sibling keys in the same block on top of the referenced content, allowing those keys to take precedence over matching keys in the reference.
* When `$ref` resolves to a non-object value such as an array, Mintlify ignores any sibling keys.
* Referenced files can contain their own `$ref` entries, resolved relative to that file.
* Paths must stay within the project root. Circular references cause a build error.
See [Split configuration with `$ref`](/organize/settings#split-configuration-with-%24ref) for examples.
***
### `theme` - required
The layout theme for your site.
**Type:** string
**Options:** `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`, `sequoia`, `luma`
See [Themes](/customize/themes) for previews.
***
### `name` - required
The name of your project, organization, or product.
**Type:** string
***
### `colors` - required
The colors used in your documentation.
**Type:** object
#### `colors.primary`
required
The primary color. Generally used for emphasis in light mode.
**Type:** string—hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`
#### `colors.light`
The color used for emphasis in dark mode.
**Type:** string—hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`
#### `colors.dark`
The color used for buttons and hover states across both modes.
**Type:** string—hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`
***
### `navigation` - required
The navigation structure of your content.
**Type:** object
See [Navigation](/organize/navigation) for complete documentation.
#### `navigation.global`
Global navigation elements that appear across all pages and locales.
**Type:** object
##### `navigation.global.tabs`
Top-level navigation tabs.
**Type:** array of object—each with: `tab` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
##### `navigation.global.anchors`
Sidebar anchor links.
**Type:** array of object—each with: `anchor` (string, required), `icon` (string), `iconType` (string), `color.light` (string hex), `color.dark` (string hex), `hidden` (boolean), `href` (string uri, required)
##### `navigation.global.dropdowns`
Dropdown menus.
**Type:** array of object—each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
##### `navigation.global.languages`
Language switcher in the global nav.
**Type:** array of object—each with: `language` (string, required), `default` (boolean), `hidden` (boolean), `href` (string uri, required)
**Supported language codes:** `ar`, `ca`, `cn`, `cs`, `da`, `de`, `en`, `es`, `fr`, `fr-CA`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `jp`, `ko`, `lv`, `nl`, `no`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `uk`, `uz`, `vi`, `zh`, `zh-Hans`, `zh-Hant`
##### `navigation.global.versions`
Version switcher in the global nav.
**Type:** array of object—each with: `version` (string, required, min length 1), `default` (boolean), `hidden` (boolean), `href` (string uri, required)
##### `navigation.global.products`
Product switcher in the global nav.
**Type:** array of object—each with: `product` (string, required), `description` (string), `icon` (string), `iconType` (string)
#### `navigation.languages`
Language switcher for multi-language sites. Each entry can include language-specific `banner`, `footer`, and `navbar` overrides.
**Type:** array of object—each with: `language` (string, required), `default` (boolean), `hidden` (boolean), `banner` (object), `footer` (object), `navbar` (object)
**Supported language codes:** `ar`, `ca`, `cn`, `cs`, `da`, `de`, `en`, `es`, `fr`, `fr-CA`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `jp`, `ko`, `lv`, `nl`, `no`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `uk`, `uz`, `vi`, `zh`, `zh-Hans`, `zh-Hant`
#### `navigation.versions`
Version switcher for multi-version sites.
**Type:** array of object—each with: `default` (boolean), `tag` (string)
#### `navigation.tabs`
Top-level navigation tabs.
**Type:** array of object—see `navigation.global.tabs` for shape.
#### `navigation.anchors`
Sidebar anchor links.
**Type:** array of object—see `navigation.global.anchors` for shape.
#### `navigation.dropdowns`
Dropdown menus.
**Type:** array of object—see `navigation.global.dropdowns` for shape.
#### `navigation.products`
Product switcher.
**Type:** array of object—see `navigation.global.products` for shape.
#### `navigation.groups`
Groups for organizing content into labeled sections.
**Type:** array of object
##### `navigation.groups[].boost`
Numeric multiplier applied to the in-product search ranking of every page in this group. Pages inherit the boost factor from the nearest ancestor group that sets one. Use values greater than `1` to prioritize, between `0` and `1` to de-prioritize. See [Search](/optimize/search#boost-search-ranking).
**Type:** number
#### `navigation.pages`
Individual pages in your documentation.
**Type:** array of string or object
#### `navigation.directory`
Directory layout for root pages in navigation groups. Inherits recursively. Descendants can override. See [Directory listings](/organize/navigation#directory-listings).
**Type:** `"none"` | `"accordion"` | `"card"`—default `"none"`
***
### `description`
Site description for SEO and AI indexing.
**Type:** string
***
### `logo`
Site logo. Provide a path string or separate `light` and `dark` objects.
**Type:** string or object
#### `logo.light`
required (when using object form)
Path to the logo for light mode. Example: `/logo/light.svg`.
**Type:** string
#### `logo.dark`
required (when using object form)
Path to the logo for dark mode. Example: `/logo/dark.svg`.
**Type:** string
#### `logo.href`
URL to redirect to when clicking the logo.
**Type:** string (uri)
***
### `favicon`
Site favicon. Automatically resized. Provide a path string or separate `light` and `dark` objects.
**Type:** string or object
#### `favicon.light`
required (when using object form)
Path to the favicon for light mode. Example: `/favicon.png`.
**Type:** string
#### `favicon.dark`
required (when using object form)
Path to the favicon for dark mode. Example: `/favicon-dark.png`.
**Type:** string
***
### `appearance`
Light/dark mode settings.
**Type:** object
#### `appearance.default`
Default color mode.
**Type:** `"system"` | `"light"` | `"dark"`
**Default:** `"system"`
#### `appearance.strict`
When `true`, hides the light/dark mode toggle.
**Type:** boolean
**Default:** `false`
***
### `fonts`
Custom fonts. Supports [Google Fonts](https://fonts.google.com) and self-hosted fonts.
**Type:** object
#### `fonts.family`
required (when using `fonts`)
Font family name. Google Fonts family names load automatically.
**Type:** string
#### `fonts.weight`
Font weight. Variable fonts support fractional values such as `550`.
**Type:** number
#### `fonts.source`
URL to a hosted font or path to a local font file. Not needed for Google Fonts.
**Type:** string (uri)
#### `fonts.format`
Font file format. Required when using `fonts.source`.
**Type:** `"woff"` | `"woff2"`
#### `fonts.heading`
Override font settings for headings. Accepts the same `family`, `weight`, `source`, and `format` fields.
**Type:** object
#### `fonts.body`
Override font settings for body text. Accepts the same `family`, `weight`, `source`, and `format` fields.
**Type:** object
***
### `icons`
Icon library settings.
**Type:** object
#### `icons.library`
required
Icon library to use throughout your documentation. All icon names in your docs must come from the selected library.
**Type:** `"fontawesome"` | `"lucide"` | `"tabler"`
**Default:** `"fontawesome"`
***
### `background`
Background image, decoration, and color settings.
**Type:** object
#### `background.decoration`
Decorative background pattern.
**Type:** `"gradient"` | `"grid"` | `"windows"`
#### `background.color`
Custom background colors.
**Type:** object
##### `background.color.light`
Background color for light mode.
**Type:** string—hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`
##### `background.color.dark`
Background color for dark mode.
**Type:** string—hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`
#### `background.image`
Background image. Provide a path string or separate `light` and `dark` objects.
**Type:** string or object
##### `background.image.light`
required (when using object form)
Background image path for light mode.
**Type:** string
##### `background.image.dark`
required (when using object form)
Background image path for dark mode.
**Type:** string
***
### `styling`
Visual styling controls.
**Type:** object
#### `styling.eyebrows`
Page eyebrow style shown at the top of the page.
**Type:** `"section"` | `"breadcrumbs"`
**Default:** `"section"`
#### `styling.latex`
Whether to load LaTeX stylesheets. By default, Mintlify auto-detects LaTeX usage.
**Type:** boolean
#### `styling.codeblocks`
Code block theme configuration.
**Type:** `"system"` | `"dark"` | string (Shiki theme name) | object
**Default:** `"system"`
When an object:
##### `styling.codeblocks.theme`
A single Shiki theme name for both modes, or an object with `light` and `dark` Shiki theme names.
**Type:** string or object
##### `styling.codeblocks.languages`
Custom language configuration.
**Type:** object
###### `styling.codeblocks.languages.custom`
Paths to JSON files describing custom Shiki languages in [TextMate grammar format](https://macromates.com/manual/en/language_grammars).
**Type:** array of string
***
### `thumbnails`
Social media thumbnail customization.
**Type:** object
#### `thumbnails.appearance`
Visual theme for thumbnails.
**Type:** `"light"` | `"dark"`
**Default:** Site color scheme
#### `thumbnails.background`
Background image for thumbnails. Can be a relative path or absolute URL.
**Type:** string
#### `thumbnails.fonts`
Font configuration for thumbnails.
**Type:** object
##### `thumbnails.fonts.family`
required (when using `thumbnails.fonts`)
Font family name. Supports [Google Fonts](https://fonts.google.com) only.
**Type:** string
***
### `navbar`
Top navigation bar configuration.
**Type:** object
#### `navbar.links`
Links displayed in the navbar.
**Type:** array of object—each with:
| Field | Type | Required | Description |
| ---------- | ------------------------- | ----------- | ------------------------------------ |
| `type` | `"github"` \| `"discord"` | No | Link type. Omit for a standard link. |
| `label` | string | Conditional | Required when `type` is omitted. |
| `href` | string (uri) | Yes | Link destination. |
| `icon` | string | No | Icon name, URL, path, or SVG. |
| `iconType` | string | No | Font Awesome icon style only. |
#### `navbar.primary`
Primary call-to-action button in the navbar.
**Type:** object
| Field | Type | Required | Description |
| ------- | --------------------------------------- | ----------- | ----------------------------------- |
| `type` | `"button"` \| `"github"` \| `"discord"` | Yes | Button style. |
| `label` | string | Conditional | Required when `type` is `"button"`. |
| `href` | string (uri) | Yes | Button destination. |
***
### `footer`
Footer content and social links.
**Type:** object
#### `footer.socials`
Social media profiles. Each key is a platform name, each value is your profile URL.
**Type:** object
**Valid keys:** `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast`
#### `footer.links`
Link columns in the footer. Maximum 4 columns.
**Type:** array of object (max 4)—each with: `header` (string), `items` (array of `{ label: string, href: string }`, required)
***
### `banner`
Site-wide banner displayed at the top of every page.
**Type:** object
#### `banner.content`
required (when using `banner`)
Banner text. Supports basic MDX formatting including links, bold, and italic. Custom components are not supported.
**Type:** string
#### `banner.dismissible`
Whether to show a dismiss button.
**Type:** boolean
**Default:** `false`
#### `banner.type`
Visual style for the banner background. Use `info` for general announcements, `warning` for cautionary notices, and `critical` for urgent issues.
**Type:** `"info"` | `"warning"` | `"critical"`
**Default:** `"info"`
#### `banner.color`
Custom background color override. Takes precedence over `type`. Banner text is white, so choose a background that remains legible.
**Type:** object with `light` (string) and `dark` (string) hex values, or a single hex string applied to both modes.
***
### `interaction`
Navigation interaction settings.
**Type:** object
#### `interaction.drilldown`
Controls automatic navigation when a user clicks a navigation group. Set to `true` to navigate to the first page when a user clicks a group, `false` to only expand/collapse the group without navigating.
**Type:** boolean
**Default:** Theme default
***
### `contextual`
Contextual menu for page actions and AI tool integrations.
**Type:** object
#### `contextual.options`
required
Actions available in the contextual menu. The first item is the default action.
**Type:** array of `"assistant"` | `"copy"` | `"view"` | `"download-pdf"` | `"download-spec"` | `"chatgpt"` | `"claude"` | `"perplexity"` | `"grok"` | `"aistudio"` | `"devin"` | `"windsurf"` | `"mcp"` | `"add-mcp"` | `"cursor"` | `"vscode"` | `"devin-mcp"` | object
Custom option object fields:
| Field | Type | Required | Description |
| ------------- | ---------------- | -------- | ----------------------------------------------------------------- |
| `title` | string | Yes | Display title. |
| `description` | string | Yes | Description text. |
| `icon` | string | No | Icon name, URL, path, or SVG. |
| `href` | string or object | Yes | Link destination. Supports `$page`, `$path`, `$mcp` placeholders. |
#### `contextual.display`
Where to show the contextual menu.
**Type:** `"header"` | `"toc"`
**Default:** `"header"`
The contextual menu is only available on preview and production deployments.
***
### `redirects`
Redirects for moved, renamed, or deleted pages.
**Type:** array of object—each with:
| Field | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------- |
| `source` | string | Yes | Path to redirect from. Example: `/old-page` |
| `destination` | string | Yes | Path to redirect to. Example: `/new-page` |
| `permanent` | boolean | No | `true` for 308, `false` for 307. Default: `true`. |
***
### `variables`
Global content variables replaced at build time using `{{variableName}}` syntax.
**Type:** object—key-value pairs where keys are variable names (alphanumeric and hyphens only) and values are replacement strings.
***
### `metadata`
Global page metadata settings.
**Type:** object
#### `metadata.timestamp`
Display a last-modified date on all pages.
**Type:** boolean
**Default:** `false`
***
### `errors`
Error page settings.
**Type:** object
#### `errors.404`
Settings for the 404 "Page not found" error page.
**Type:** object
##### `errors.404.redirect`
Whether to automatically redirect to the home page when a page is not found.
**Type:** boolean
**Default:** `true`
##### `errors.404.title`
Custom title for the 404 page.
**Type:** string
##### `errors.404.description`
Custom description for the 404 page. Supports MDX formatting including links, bold, italic, and custom components.
**Type:** string
***
### `api`
API documentation and playground settings.
**Type:** object
#### `api.openapi`
OpenAPI specification files.
**Type:** string | array of string | object with `source` (string) and `directory` (string)
#### `api.asyncapi`
AsyncAPI specification files.
**Type:** string | array of string | object with `source` (string) and `directory` (string)
#### `api.playground`
Interactive playground settings.
**Type:** object
##### `api.playground.display`
Playground display mode.
**Type:** `"interactive"` | `"simple"` | `"none"` | `"auth"`
**Default:** `"interactive"`
##### `api.playground.proxy`
Whether to route API requests through a proxy.
**Type:** boolean
**Default:** `true`
##### `api.playground.credentials`
Whether to include cookies and authentication headers for cross-origin requests when `proxy` is `false`. Has no effect when `proxy` is `true`.
**Type:** boolean
**Default:** `false`
#### `api.params`
API parameter display settings.
**Type:** object
##### `api.params.expanded`
Whether to expand all parameters by default.
**Type:** `"all"` | `"closed"`
**Default:** `"closed"`
##### `api.params.post`
OpenAPI spec field keys to surface as post pills next to every parameter name. For each key, Mintlify reads the value on the schema and renders it as a pill: strings render verbatim, `true` renders the key name, numbers stringify, and arrays render one pill per element. Mintlify skips `false`, `null`, empty strings, and objects.
**Type:** array of string
#### `api.url`
Base URL display mode.
**Type:** `"full"`
**Default:** Only shown when multiple base URLs exist.
#### `api.examples`
Code example settings.
**Type:** object
##### `api.examples.languages`
Languages for autogenerated code snippets. See [supported languages](/api-playground/overview#all-supported-languages).
**Type:** array of string
##### `api.examples.defaults`
Whether to include optional parameters in examples.
**Type:** `"required"` | `"all"`
**Default:** `"all"`
##### `api.examples.prefill`
Whether to prefill playground fields with spec example values.
**Type:** boolean
**Default:** `false`
##### `api.examples.autogenerate`
Whether to generate code samples from API specifications.
**Type:** boolean
**Default:** `true`
#### `api.mdx`
Settings for API pages built from MDX files.
**Type:** object
##### `api.mdx.auth`
Authentication configuration for MDX-based API requests.
**Type:** object
###### `api.mdx.auth.method`
Authentication method.
**Type:** `"bearer"` | `"basic"` | `"key"` | `"cobo"`
###### `api.mdx.auth.name`
Authentication parameter name.
**Type:** string
##### `api.mdx.server`
Base URL prepended to relative paths in page-level `api` frontmatter. Not used when frontmatter contains a full URL.
**Type:** string or array
***
### `seo`
Search engine optimization settings.
**Type:** object
#### `seo.indexing`
Which pages search engines should index.
**Type:** `"navigable"` | `"all"`
**Default:** `"navigable"`
#### `seo.metatags`
Custom meta tags added to every page. Key-value pairs.
**Type:** object
***
### `search`
Search bar settings.
**Type:** object
#### `search.prompt`
Placeholder text in the search bar.
**Type:** string
***
### `integrations`
Third-party integrations.
**Type:** object
| Property | Type | Required field | Description |
| --------------------------------------- | ------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `integrations.adobe.launchUrl` | string (uri) | Yes | Adobe Analytics launch URL. |
| `integrations.amplitude.apiKey` | string | Yes | Amplitude API key. |
| `integrations.clarity.projectId` | string | Yes | Microsoft Clarity project ID. |
| `integrations.clearbit.publicApiKey` | string | Yes | Clearbit public API key. |
| `integrations.fathom.siteId` | string | Yes | Fathom site ID. |
| `integrations.frontchat.snippetId` | string (min 6) | Yes | Front chat snippet ID. |
| `integrations.ga4.measurementId` | string (must start with `G`) | Yes | Google Analytics 4 measurement ID. |
| `integrations.gtm.tagId` | string (must start with `G`) | Yes | Google Tag Manager container ID. |
| `integrations.heap.appId` | string | Yes | Heap app ID. |
| `integrations.hightouch.writeKey` | string | Yes | Hightouch write key. |
| `integrations.hightouch.apiHost` | string | No | Hightouch API host. |
| `integrations.hotjar.hjid` | string | Yes | Hotjar site ID. |
| `integrations.hotjar.hjsv` | string | Yes | Hotjar script version. |
| `integrations.intercom.appId` | string (min 6) | Yes | Intercom app ID. |
| `integrations.logrocket.appId` | string | Yes | LogRocket app ID. |
| `integrations.mixpanel.projectToken` | string | Yes | Mixpanel project token. |
| `integrations.pirsch.id` | string | Yes | Pirsch site ID. |
| `integrations.plausible.domain` | string | Yes | Plausible domain. |
| `integrations.plausible.server` | string | No | Plausible server (self-hosted only). |
| `integrations.posthog.apiKey` | string (must start with `phc_`) | Yes | PostHog API key. |
| `integrations.posthog.apiHost` | string (uri) | No | PostHog API host (self-hosted only). |
| `integrations.posthog.sessionRecording` | boolean | No | Enable session recording. Default: `false`. |
| `integrations.segment.key` | string | Yes | Segment write key. |
| `integrations.telemetry.enabled` | boolean | No | Enable Mintlify telemetry. When `false`, feedback features are also disabled. |
| `integrations.cookies.key` | string | No | Cookie key name. |
| `integrations.cookies.value` | string | No | Cookie value. |
## Related topics
- [Global settings](/docs/organize/settings.md)
- [Markdown export](/docs/ai/markdown-export.md)
- [Commands](/docs/cli/commands.md)