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
• Site structure
• API settings
• Integrations
• SEO and search

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. Those keys 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.

{
  "navigation": { "$ref": "./navigation.json" }
}

See Split configuration with $ref for more examples.

The layout theme for your site.

Type: string Options: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma

See Themes for previews.

The name of your project, organization, or product.

Type: string

The colors used in your documentation.

Type: object

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})$

The color used for emphasis in dark mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

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})$

The navigation structure of your content.

Type: object

See Navigation for complete documentation.

Global navigation elements that appear across all pages and locales.

Type: object

Top-level navigation tabs.

Type: array of object—each with: tab (string, required), icon (string), iconType (string), hidden (boolean), href (string uri, required)

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)

Dropdown menus.

Type: array of object—each with: dropdown (string, required), icon (string), iconType (string), hidden (boolean), href (string uri, required)

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, ja-JP, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, uz, vi, zh, zh-CN, zh-Hans, zh-Hant, zh-TW

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)

Product switcher in the global nav.

Type: array of object—each with: product (string, required), description (string), icon (string), iconType (string)

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, ja-JP, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, uz, vi, zh, zh-CN, zh-Hans, zh-Hant, zh-TW

Version switcher for multi-version sites.

Type: array of object—each with: default (boolean), tag (string)

Top-level navigation tabs.

Type: array of object—see navigation.global.tabs for shape.

Sidebar anchor links.

Type: array of object—see navigation.global.anchors for shape.

Dropdown menus.

Type: array of object—see navigation.global.dropdowns for shape.

Product switcher. Each entry requires a product field. It can contain groups, pages, a menu array (same shape as navigation.tabs[].menu, for multi-column product dropdowns), icons, or external links.

Type: array of object—each with: product (string, required), description (string), icon (string), iconType (string), href (string uri), groups (array), pages (array), menu (array)

Groups for organizing content into labeled sections.

Type: array of object

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 pages. Use values between 0 and 1 to de-prioritize them. See Search.

Type: number

Individual pages in your documentation.

Type: array of string or object

Directory layout for root pages in navigation groups. Inherits recursively. Descendants can override. See Directory listings.

Type: "none" | "accordion" | "card"—default "none"

Site description for SEO and AI indexing.

Type: string

Site logo. Provide a path string or separate light and dark objects.

Type: string or object

required (when using object form)

Path to the logo for light mode. Example: /logo/light.svg.

Type: string

required (when using object form)

Path to the logo for dark mode. Example: /logo/dark.svg.

Type: string

URL to redirect to when clicking the logo.

Type: string (uri)

Site favicon. Automatically resized. Provide a path string or separate light and dark objects.

Type: string or object

required (when using object form)

Path to the favicon for light mode. Example: /favicon.png.

Type: string

required (when using object form)

Path to the favicon for dark mode. Example: /favicon-dark.png.

Type: string

Light/dark mode settings.

Type: object

Default color mode.

Type: "system" | "light" | "dark" Default: "system"

When true, hides the light/dark mode toggle.

Type: boolean Default: false

Custom fonts. Supports Google Fonts and self-hosted fonts.

Type: object

required (when using fonts)

Font family name. Google Fonts family names load automatically.

Type: string

Font weight. Variable fonts support fractional values such as 550.

Type: number

URL to a hosted font or path to a local font file. Not needed for Google Fonts.

Type: string (uri)

Font file format. Required when using fonts.source.

Type: "woff" | "woff2"

Override font settings for headings. Accepts the same family, weight, source, and format fields.

Type: object

Override font settings for body text. Accepts the same family, weight, source, and format fields.

Type: object

Icon library settings.

Type: object

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 image, decoration, and color settings.

Type: object

Decorative background pattern.

Type: "gradient" | "grid" | "windows"

Custom background colors.

Type: object

Background color for light mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Background color for dark mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Background image. Provide a path string or separate light and dark objects.

Type: string or object

required (when using object form)

Background image path for light mode.

Type: string

required (when using object form)

Background image path for dark mode.

Type: string

Visual styling controls.

Type: object

Page eyebrow style shown at the top of the page.

Type: "section" | "breadcrumbs" Default: "section"

Whether to load LaTeX stylesheets. By default, Mintlify auto-detects LaTeX usage.

Type: boolean

Code block theme configuration.

Type: "system" | "dark" | string (Shiki theme name) | object Default: "system"

When an object:

A single Shiki theme name for both modes, or an object with light and dark Shiki theme names.

Type: string or object

Custom language configuration.

Type: object

Paths to JSON files describing custom Shiki languages in TextMate grammar format.

Type: array of string

Social media thumbnail customization.

Type: object

Visual theme for thumbnails.

Type: "light" | "dark" Default: Site color scheme

Background image for thumbnails. Can be a relative path or absolute URL.

Type: string

Font configuration for thumbnails.

Type: object

required (when using thumbnails.fonts)

Font family name. Supports Google Fonts only.

Type: string

Top navigation bar configuration.

Type: object

Links displayed in the navbar.

Type: array of object—each with:

Primary call-to-action button in the navbar.

Type: object

Footer content and social links.

Type: object

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

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)

Site-wide banner displayed at the top of every page.

Type: object

required (when using banner)

Banner text. Supports basic MDX formatting including links, bold, and italic. Custom components are not supported.

Type: string

Whether to show a dismiss button.

Type: boolean Default: false

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"

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.

Navigation interaction settings.

Type: object

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. Set to false to only expand/collapse the group without navigating.

Type: boolean Default: Theme default

Contextual menu for page actions and AI tool integrations.

Type: object

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" | "devin-desktop" | "mcp" | "add-mcp" | "cursor" | "vscode" | "devin-mcp" | object

Custom option object fields:

Where to show the contextual menu.

Type: "header" | "toc" Default: "header"

Redirects for moved, renamed, or deleted pages.

Type: array of object—each with:

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.

Global page metadata settings.

Type: object

Display a last-modified date on all pages. For projects backed by GitHub or GitLab, the date reflects the last Git commit that touched a page's source file. It falls back to the most recent deployment timestamp if a Git commit date isn't available.

Set the lastUpdatedDate frontmatter field on a page to override the automatic date. See Pages for details.

Type: boolean Default: false

Error page settings.

Type: object

Settings for the 404 "Page not found" error page.

Type: object

Whether to automatically redirect to the home page when a page is not found.

Type: boolean Default: true

Custom title for the 404 page.

Type: string

Custom description for the 404 page. Supports MDX formatting including links, bold, italic, and custom components.

Type: string

API documentation and playground settings.

Type: object

OpenAPI specification files.

Type: string | array of string or object | object with source (string), directory (string), and overlays (array of string)

AsyncAPI specification files.

Type: string | array of string | object with source (string) and directory (string)

Interactive playground settings.

Type: object

Playground display mode.

Type: "interactive" | "simple" | "none" | "auth" Default: "interactive"

Whether to route API requests through a proxy.

Type: boolean Default: true

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 parameter display settings.

Type: object

Whether to expand all parameters by default.

Type: "all" | "closed" Default: "closed"

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

Base URL display mode.

Type: "full" Default: Only shown when multiple base URLs exist.

Code example settings.

Type: object

Languages for autogenerated code snippets. See supported languages.

Type: array of string

Whether to include optional parameters in examples.

Type: "required" | "all" Default: "all"

Whether to prefill playground fields with spec example values.

Type: boolean Default: false

Whether to generate code samples from API specifications.

Type: boolean Default: true

Settings for API pages built from MDX files.

Type: object

Authentication configuration for MDX-based API requests.

Type: object

Authentication method.

Type: "bearer" | "basic" | "key" | "cobo"

Authentication parameter name.

Type: string

Base URL prepended to relative paths in page-level api frontmatter. Not used when frontmatter contains a full URL.

Type: string or array

Settings for the Markdown that Mintlify serves to AI tools and agents. See Markdown export.

Type: object

Whether to include the full OpenAPI or AsyncAPI specification in the Markdown export of API reference pages.

Type: boolean Default: true

Custom agent instructions appended to the generated Markdown of every page, as well as your llms.txt and llms-full.txt files. Provide a single string or an array of strings. Mintlify joins array items with line breaks. See Custom agent instructions.

Type: string or array of strings

Search engine optimization settings.

Type: object

Which pages search engines should index.

Type: "navigable" | "all" Default: "navigable"

Custom meta tags added to every page. Key-value pairs.

Type: object

Organization used as the publisher entity in structured data (JSON-LD) on every page. It accepts id, name, legalName, url, logo, and sameAs. See SEO and search.

Type: object

Search bar settings.

Type: object

Placeholder text in the search bar.

Type: string

Third-party integrations.

Type: object

• Mintlify CLI command reference
• SEO
• API playground overview