skills/mintlify__docs
1
0
Fork 0
mirror of https://github.com/mintlify/docs.git synced 2026-09-14 13:35:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
sam/ai-commit-message
mintlify__docs/organize/settings.mdx
T

1673 lines
56 KiB
Plaintext
Raw Permalink Blame History

---
title: "Global settings"
description: "Configure site-wide settings in docs.json."
keywords: ["docs.json", "settings", "customization", "configuration", "logo", "colors", "fonts", "background", "appearance", "last modified date", "timestamp"]
---
import IconsOptional from "/snippets/icons-optional.mdx";
The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. Think of it as the blueprint for your documentation.
Settings in `docs.json` apply globally to all pages.
## Setting up your `docs.json`
To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow.
For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors:
```json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Your Docs",
"colors": {
"primary": "#ff0000"
},
"navigation": {
// Your navigation structure
}
// The rest of your configuration
}
```
## Reference
This section contains the full reference for the `docs.json` file.
### Customization
<ResponseField name="theme" required>
The layout theme of your site.
One of the following: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`.
See [Themes](/customize/themes) for more information.
</ResponseField>
<ResponseField name="name" type="string" required>
The name of your project, organization, or product.
</ResponseField>
<ResponseField name="colors" type="object" required>
The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it applies to all color elements.
<Expandable title="Colors">
<ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
The primary color for your documentation. Generally used for emphasis in light mode, with some variation by theme.
Must be a hex code beginning with `#`.
</ResponseField>
<ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
The color used for emphasis in dark mode.
Must be a hex code beginning with `#`.
</ResponseField>
<ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
The color used for buttons and hover states across both light and dark modes, with some variation by theme.
Must be a hex code beginning with `#`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="description" type="string">
Description of your site for SEO and AI indexing.
</ResponseField>
<ResponseField name="logo" type="string or object">
Set your logo for both light and dark mode.
<Expandable title="Logo">
<ResponseField name="light" type="string" required>
Path pointing to your logo file for light mode. Include the file extension. Example: `/logo.png`
</ResponseField>
<ResponseField name="dark" type="string" required>
Path pointing to your logo file for dark mode. Include the file extension. Example: `/logo-dark.png`
</ResponseField>
<ResponseField name="href" type="string (uri)">
The URL to redirect to when clicking the logo. If not provided, the logo links to your homepage. Example: `https://mintlify.com`
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="favicon" type="string or object">
Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. Can be a single file or separate files for light and dark mode. Example: `/favicon.png`
<Expandable title="Favicon">
<ResponseField name="light" type="string" required>
Path to your favicon file for light mode. Include the file extension. Example: `/favicon.png`
</ResponseField>
<ResponseField name="dark" type="string" required>
Path to your favicon file for dark mode. Include the file extension. Example: `/favicon-dark.png`
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="thumbnails" type="object">
Thumbnail customization for social media and page previews.
<Expandable title="Thumbnails">
<ResponseField name="appearance" type='"light" | "dark"'>
The visual theme of your thumbnails. If not specified, thumbnails use your site's color scheme defined by the `colors` field.
</ResponseField>
<ResponseField name="background" type="string">
Background image for your thumbnails. Can be a relative path or absolute URL.
</ResponseField>
<ResponseField name="fonts" type="object">
Font configuration for thumbnails. Only supports Google Fonts family names.
<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Font family name, such as "Open Sans" or "Playfair Display". Supports [Google Fonts](https://fonts.google.com) family names.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="styling" type="object">
Visual styling configurations.
<Expandable title="Styling">
<ResponseField name="eyebrows" type='"section" | "breadcrumbs"'>
The style of the page eyebrow. Choose `section` to show the section name or `breadcrumbs` to show the full navigation path. Defaults to `section`.
</ResponseField>
<ResponseField name="latex" type="boolean">
Controls whether LaTeX stylesheets are included, overriding automatic detection. By default, Mintlify automatically detects LaTeX usage in your content and loads the necessary stylesheets.
- Set to `true` to force-load LaTeX stylesheets when automatic detection fails to recognize your mathematical expressions.
- Set to `false` to prevent loading LaTeX stylesheets for improved performance if you don't use mathematical expressions but have content that triggers false-positive detection.
</ResponseField>
<ResponseField name="codeblocks" type='"system" | "dark" | string | object'>
Code block theme configuration. Defaults to `"system"`.
**Simple configuration:**
- `"system"`: Match current site mode (light or dark)
- `"dark"`: Always use dark mode
**Custom theme configuration:**
- Use a string to specify a single [Shiki theme](https://shiki.style/themes) for all code blocks
- Use an object to specify separate [Shiki themes](https://shiki.style/themes) for light and dark modes
<ResponseField name="theme" type="string">
A single Shiki theme name to use for both light and dark modes.
```json
"styling": {
"codeblocks": {
"theme": "dracula"
}
}
```
</ResponseField>
<ResponseField name="theme" type="object">
Separate themes for light and dark modes.
<Expandable title="theme">
<ResponseField name="light" type="string" required>
A Shiki theme name for light mode.
</ResponseField>
<ResponseField name="dark" type="string" required>
A Shiki theme name for dark mode.
</ResponseField>
```json
"styling": {
"codeblocks": {
"theme": {
"light": "github-light",
"dark": "github-dark"
}
}
}
```
</Expandable>
</ResponseField>
<ResponseField name="languages" type="object">
Custom language configuration for code blocks.
<Expandable title="languages">
<ResponseField name="custom" type="array of string">
Paths to JSON files describing custom Shiki languages. Use this to add syntax highlighting for languages not included in Shiki's default set.
The JSON file must follow the [TextMate grammar format](https://macromates.com/manual/en/language_grammars) used by Shiki.
```json
"styling": {
"codeblocks": {
"languages": {
"custom": ["/languages/my-custom-language.json"]
}
}
}
```
</ResponseField>
</Expandable>
</ResponseField>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="icons" type="object">
Icon library settings.
<Expandable title="Icons">
<ResponseField name="library" type='"fontawesome" | "lucide"' required>
Icon library to use throughout your documentation. Defaults to `fontawesome`.
You can only use one icon library for your project. All icon names in your documentation must come from the same library.
<Note>
You can specify a URL to an externally hosted icon or a path to an icon file in your project for any individual icon, regardless of the library setting.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="fonts" type="object">
Set custom fonts for your documentation. The default font varies by theme.
<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans." Supports [Google Fonts](https://fonts.google.com) family names.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:
- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.
[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type='"woff" | "woff2"'>
Font file format. Required when using the `source` field.
</ResponseField>
<ResponseField name="heading" type="object">
Override font settings specifically for headings.
<Expandable title="Heading">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans", "Playfair Display." Supports [Google Fonts](https://fonts.google.com) family names.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:
- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.
[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="&quot;woff&quot; | &quot;woff2&quot;">
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="body" type="object">
Override font settings specifically for body text.
<Expandable title="Body">
<ResponseField name="family" type="string" required>
Font family, such as "Open Sans", "Playfair Display." Supports [Google Fonts](https://fonts.google.com) family names.
</ResponseField>
<ResponseField name="weight" type="number">
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
One of:
- URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
- Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.
[Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
</ResponseField>
<ResponseField name="format" type="&quot;woff&quot; | &quot;woff2&quot;">
Font file format. Required when using the `source` field.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="appearance" type="object">
Light/dark mode toggle settings.
<Expandable title="Appearance">
<ResponseField name="default" type='"system" | "light" | "dark"'>
Default theme mode. Choose `system` to match users' OS settings, or `light` or `dark` to force a specific mode. Defaults to `system`.
</ResponseField>
<ResponseField name="strict" type="boolean">
Whether to hide the light/dark mode toggle. Defaults to `false`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="background" type="object">
Background color and decoration settings.
<Expandable title="Background">
<ResponseField name="image" type="string or object">
Background image for your site. Can be a single file or separate files for light and dark mode.
<Expandable title="Image">
<ResponseField name="light" type="string" required>
Path to your background image for light mode. Include the file extension. Example: `/background.png`.
</ResponseField>
<ResponseField name="dark" type="string" required>
Path to your background image for dark mode. Include the file extension. Example: `/background-dark.png`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="decoration" type='"gradient" | "grid" | "windows"'>
Background decoration for your theme.
</ResponseField>
<ResponseField name="color" type="object">
Custom background colors for light and dark modes.
<Expandable title="Color">
<ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
Background color for light mode.
Must be a hex code beginning with `#`.
</ResponseField>
<ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
Background color for dark mode.
Must be a hex code beginning with `#`.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Structure
<ResponseField name="navbar" type="object">
Navigation bar items to external links.
<Expandable title="Navbar">
<ResponseField name="links" type="array of object">
Links to display in the navbar
<Expandable title="Links">
<ResponseField name="label" type="string" required>
Text for the link.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
Link destination. Must be a valid external URL.
</ResponseField>
<IconsOptional />
</Expandable>
</ResponseField>
<ResponseField name="primary" type="object">
Primary button in the navbar.
<Expandable title="Primary">
<ResponseField name="type" type='"button" | "github"' required>
Button style. Choose `button` for a standard button with a label or `github` for a link to a GitHub repository with icon.
</ResponseField>
<ResponseField name="label" type="string" required>
Button text. Only applies when `type` is `button`.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
Button destination. Must be an external URL. If `type` is `github`, must be a GitHub repository URL.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="navigation" type="object" required>
The navigation structure of your content.
<Expandable title="Navigation">
<ResponseField name="global" type="object">
Global navigation elements that appear across all pages and sections.
<Expandable title="Global">
<ResponseField name="languages" type="array of object">
Language switcher configuration for localized sites.
<Expandable title="Languages">
<ResponseField name="language" type='"en" | "cn" | "zh" | "zh-Hans" | "zh-Hant" | "es" | "fr" | "ja" | "jp" | "pt" | "pt-BR" | "de" | "ko" | "it" | "ru" | "id" | "ar" | "tr"' required>
Language code in ISO 639-1 format
</ResponseField>
<ResponseField name="default" type="boolean">
Whether this is the default language.
</ResponseField>
<ResponseField name="hidden" type="boolean">
Whether to hide this language option by default.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
A valid path or external link to this language version of your documentation.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="versions" type="array of object">
Version switcher configuration for multi-version sites.
<Expandable title="Versions">
<ResponseField name="version" type="string" required>
Display name of the version.
Minimum length: 1
</ResponseField>
<ResponseField name="default" type="boolean">
Whether this is the default version.
</ResponseField>
<ResponseField name="hidden" type="boolean">
Whether to hide this version option by default.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
URL or path to this version of your documentation.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="tabs" type="array of object">
Top-level navigation tabs for organizing major sections.
<Expandable title="Tabs">
<ResponseField name="tab" type="string" required>
Display name of the tab.
Minimum length: 1
</ResponseField>
<IconsOptional />
<ResponseField name="hidden" type="boolean">
Whether to hide this tab by default.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
URL or path for the tab destination.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="anchors" type="array of object">
Anchored links that appear prominently in the sidebar navigation.
<Expandable title="Anchors">
<ResponseField name="anchor" type="string" required>
Display name of the anchor.
Minimum length: 1
</ResponseField>
<IconsOptional />
<ResponseField name="color" type="object">
Custom colors for the anchor.
<Expandable title="Color">
<ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
Anchor color for light mode.
Must be a hex code beginning with `#`.
</ResponseField>
<ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
Anchor color for dark mode.
Must be a hex code beginning with `#`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="hidden" type="boolean">
Whether to hide this anchor by default.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
URL or path for the anchor destination.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="dropdowns" type="array of object">
Dropdown menus for organizing related content.
<Expandable title="Dropdowns">
<ResponseField name="dropdown" type="string" required>
Display name of the dropdown.
Minimum length: 1
</ResponseField>
<IconsOptional />
<ResponseField name="hidden" type="boolean">
Whether to hide this dropdown by default.
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
URL or path for the dropdown destination.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="products" type="array of object">
Products for organizing content into sections.
<Expandable title="Products">
<ResponseField name="product" type="string" required>
Display name of the product.
</ResponseField>
<ResponseField name="description" type="string">
Description of the product.
</ResponseField>
<IconsOptional />
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="languages" type="array of object">
Language switcher for [multi-language](/organize/navigation#languages) sites.
</ResponseField>
<ResponseField name="versions" type="array of object">
Version switcher for sites with multiple [versions](/organize/navigation#versions).
</ResponseField>
<ResponseField name="tabs" type="array of object">
Top-level navigation [tabs](/organize/navigation#tabs).
</ResponseField>
<ResponseField name="anchors" type="array of object">
Sidebar [anchors](/organize/navigation#anchors).
</ResponseField>
<ResponseField name="dropdowns" type="array of object">
[Dropdowns](/organize/navigation#dropdowns) for grouping related content.
</ResponseField>
<ResponseField name="products" type="array of object">
Product switcher for sites with multiple [products](/organize/navigation#products).
</ResponseField>
<ResponseField name="groups" type="array of object">
[Groups](/organize/navigation#groups) for organizing content into sections.
</ResponseField>
<ResponseField name="pages" type="array of string or object">
Individual [pages](/organize/navigation#pages) that make up your documentation.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="interaction" type="object">
User interaction settings for navigation elements.
<Expandable title="Interaction">
<ResponseField name="drilldown" type="boolean">
Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group expands. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="metadata" type="object">
Metadata configuration for documentation pages.
<Expandable title="Metadata">
<ResponseField name="timestamp" type="boolean">
Enable the last modified date on all pages. When enabled, all pages display the date the content was last modified. Defaults to `false`.
You can override this setting on individual pages with the `timestamp` frontmatter field. See [Pages](/organize/pages#last-modified-timestamp) for more information.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="footer" type="object">
Footer content and social media links.
<Expandable title="Footer">
<ResponseField name="socials" type="object">
Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example:
```json
{
"x": "https://x.com/mintlify"
}
```
Valid property names: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast`
</ResponseField>
<ResponseField name="links" type="array of object">
Links to display in the footer.
<Expandable title="Links">
<ResponseField name="header" type="string">
Header title for the column.
Minimum length: 1
</ResponseField>
<ResponseField name="items" type="array of object" required>
Links to display in the column.
<Expandable title="Items">
<ResponseField name="label" type="string" required>
Link text.
Minimum length: 1
</ResponseField>
<ResponseField name="href" type="string (uri)" required>
Link destination URL.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="banner" type="object">
Site-wide banner displayed at the top of pages.
<Expandable title="Banner">
<ResponseField name="content" type="string" required>
The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported. For example:
```json
{
"content": "🚀 Banner is live! [Learn more](mintlify.com)"
}
```
</ResponseField>
<ResponseField name="dismissible" type="boolean">
Whether to show the dismiss button on the right side of the banner. Defaults to `false`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="redirects" type="array of object">
Redirects for moved, renamed, or deleted pages.
<Expandable title="Redirects">
<ResponseField name="source" type="string" required>
Source path to redirect from. Example: `/old-page`
</ResponseField>
<ResponseField name="destination" type="string" required>
Destination path to redirect to. Example: `/new-page`
</ResponseField>
<ResponseField name="permanent" type="boolean">
Whether to use a permanent redirect (301). Defaults to `true`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="contextual" type="object">
Contextual menu for AI-optimized content and integrations.
<Expandable title="Contextual">
<ResponseField name="options" type='array of "copy" | "view" | "chatgpt" | "claude" | "perplexity" | "mcp" | "cursor" | "vscode" | object' required>
Actions available in the contextual menu. The first option appears as the default.
- `copy`: Copy the current page as Markdown to the clipboard.
- `view`: View the current page as Markdown in a new tab.
- `chatgpt`: Send the current page content to ChatGPT.
- `claude`: Send the current page content to Claude.
- `perplexity`: Send the current page content to Perplexity.
- `mcp`: Copies your MCP server URL to the clipboard.
- `cursor`: Installs your hosted MCP server in Cursor.
- `vscode`: Installs your hosted MCP server in VSCode.
Define custom contextual menu options as objects with the following properties:
<Expandable title="Custom option">
<ResponseField name="title" type="string" required>
Display title for the custom option.
</ResponseField>
<ResponseField name="description" type="string" required>
Description text for the custom option.
</ResponseField>
<ResponseField name="icon" type="string">
Icon for the custom option. Supports icon library names, URLs, paths, or SVG code.
</ResponseField>
<ResponseField name="href" type="string or object" required>
Link destination for the custom option. Can be a simple URL string or an object with `base` and optional `query` parameters.
Placeholder values:
- `$page`: Current page content
- `$path`: Current page path
- `$mcp`: MCP server URL
</ResponseField>
</Expandable>
<img
src="/images/page-context-menu.png"
alt="Contextual Menu"
className="rounded-xl"
/>
<Note>
The contextual menu is only available on preview and production deployments.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
### API configurations
<ResponseField name="api" type="object">
API documentation and interactive playground settings.
<Expandable title="api">
<ResponseField name="openapi" type="string or array or object">
OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
<Expandable title="openapi">
<ResponseField name="source" type="string">
URL or path to your OpenAPI specification file.
Minimum length: 1
</ResponseField>
<ResponseField name="directory" type="string">
Directory to search for OpenAPI files.
Do not include a leading slash.
</ResponseField>
</Expandable>
<CodeGroup>
```json Single file
"openapi": "openapi.json"
```
```json Multiple files
"openapi": [
"openapi/v1.json",
"openapi/v2.json",
"https://api.example.com/openapi.yaml"
]
```
```json Directory
"openapi": {
"source": "openapi.json",
"directory": "api-docs"
}
```
</CodeGroup>
</ResponseField>
<ResponseField name="asyncapi" type="string or array or object">
AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
<Expandable title="asyncapi">
<ResponseField name="source" type="string">
URL or path to your AsyncAPI specification file.
Minimum length: 1
</ResponseField>
<ResponseField name="directory" type="string">
Directory to search for AsyncAPI files.
Do not include a leading slash.
</ResponseField>
</Expandable>
<CodeGroup>
```json Single file
"asyncapi": "asyncapi.json"
```
```json Multiple files
"asyncapi": [
"asyncapi/events.yaml",
"asyncapi/webhooks.yaml",
"https://api.example.com/asyncapi.json"
]
```
```json Directory
"asyncapi": {
"source": "asyncapi.json",
"directory": "websockets"
}
```
</CodeGroup>
</ResponseField>
<ResponseField name="params" type="object">
Display settings for API parameters.
<Expandable title="Params">
<ResponseField name="expanded" type='"all" | "closed"'>
Whether to expand all parameters by default. Defaults to `closed`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="playground" type="object">
API playground settings.
<Expandable title="Playground">
<ResponseField name="display" type='"interactive" | "simple" | "none"'>
The display mode of the API playground. Defaults to `interactive`.
</ResponseField>
<ResponseField name="proxy" type="boolean">
Whether to pass API requests through a proxy server. Defaults to `true`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="examples" type="object">
Configurations for the autogenerated API examples.
<Expandable title="Examples">
<ResponseField name="languages" type="array of string">
Example languages for the autogenerated API snippets. Supported languages include:
- `bash` (displayed as cURL)
- `go`
- `java`
- `javascript`
- `node` (displayed as Node.js)
- `php`
- `powershell`
- `python`
- `ruby`
- `swift`
Common aliases are also supported: `curl`, `golang`, `js`, `nodejs`, `rb`, `sh`.
</ResponseField>
<ResponseField name="defaults" type='"required" | "all"'>
Whether to show optional parameters in API examples. Defaults to `all`.
</ResponseField>
<ResponseField name="prefill" type="boolean">
Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
</ResponseField>
<ResponseField name="autogenerate" type="boolean">
Whether to generate code samples for endpoints from API specifications. Defaults to `true`. When set to `false`, only manually-written code samples (from `x-codeSamples` in OpenAPI specifications or `<RequestExample>` components in MDX) appear in the API playground.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="mdx" type="object">
Configurations for API pages generated from MDX files.
<Expandable title="Mdx">
<ResponseField name="auth" type="object">
Authentication configuration for MDX-based API requests.
<Expandable title="Auth">
<ResponseField name="method" type='"bearer" | "basic" | "key" | "cobo"'>
Authentication method for API requests.
</ResponseField>
<ResponseField name="name" type="string">
Authentication name for API requests.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="server" type="string or array">
Base URL prepended to relative paths in page-level `api` frontmatter fields. Not used when the frontmatter contains a full URL.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### SEO and search
<ResponseField name="seo" type="object">
SEO indexing configurations.
<Expandable title="Seo">
<ResponseField name="metatags" type="object">
Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/optimize/seo#common-meta-tags-reference) for options.
</ResponseField>
<ResponseField name="indexing" type='"navigable" | "all"'>
Specify which pages search engines should index. Choose `navigable` to index only pages that are in your `docs.json` navigation or choose `all` to index every page. Defaults to `navigable`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="search" type="object">
Search display settings.
<Expandable title="Search">
<ResponseField name="prompt" type="string">
Placeholder text to display in the search bar.
</ResponseField>
</Expandable>
</ResponseField>
### Integrations
<ResponseField name="integrations" type="object">
Third-party integrations.
<Expandable title="Integrations">
<ResponseField name="amplitude" type="object">
Amplitude analytics integration.
<Expandable title="Amplitude">
<ResponseField name="apiKey" type="string" required>
Your Amplitude API key.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="clarity" type="object">
Microsoft Clarity integration.
<Expandable title="Clarity">
<ResponseField name="projectId" type="string" required>
Your Microsoft Clarity project ID.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="clearbit" type="object">
Clearbit data enrichment integration.
<Expandable title="Clearbit">
<ResponseField name="publicApiKey" type="string" required>
Your Clearbit API key.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="fathom" type="object">
Fathom analytics integration.
<Expandable title="Fathom">
<ResponseField name="siteId" type="string" required>
Your Fathom site ID.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="frontchat" type="object">
Front chat integration.
<Expandable title="Frontchat">
<ResponseField name="snippetId" type="string" required>
Your Front chat snippet ID.
Minimum length: 6
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="ga4" type="object">
Google Analytics 4 integration.
<Expandable title="Ga4">
<ResponseField name="measurementId" type="string matching ^G" required>
Your Google Analytics 4 measurement ID.
Must match pattern: ^G
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="gtm" type="object">
Google Tag Manager integration.
<Expandable title="Gtm">
<ResponseField name="tagId" type="string matching ^G" required>
Your Google Tag Manager tag ID.
Must match pattern: ^G
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="heap" type="object">
Heap analytics integration.
<Expandable title="Heap">
<ResponseField name="appId" type="string" required>
Your Heap app ID.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="hightouch" type="object">
Hightouch integration.
<Expandable title="Hightouch">
<ResponseField name="writeKey" type="string" required>
Your Hightouch write key.
</ResponseField>
<ResponseField name="apiHost" type="string">
Your Hightouch API host.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="hotjar" type="object">
Hotjar integration.
<Expandable title="Hotjar">
<ResponseField name="hjid" type="string" required>
Your Hotjar ID.
</ResponseField>
<ResponseField name="hjsv" type="string" required>
Your Hotjar script version.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="intercom" type="object">
Intercom integration.
<Expandable title="Intercom">
<ResponseField name="appId" type="string" required>
Your Intercom app ID.
Minimum length: 6
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="logrocket" type="object">
LogRocket integration.
<Expandable title="Logrocket">
<ResponseField name="appId" type="string" required>
Your LogRocket app ID.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="mixpanel" type="object">
Mixpanel integration.
<Expandable title="Mixpanel">
<ResponseField name="projectToken" type="string" required>
Your Mixpanel project token.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="osano" type="object">
Osano integration.
<Expandable title="Osano">
<ResponseField name="scriptSource" type="string" required>
Your Osano script source.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="pirsch" type="object">
Pirsch analytics integration.
<Expandable title="Pirsch">
<ResponseField name="id" type="string" required>
Your Pirsch ID.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="posthog" type="object">
PostHog integration.
<Expandable title="Posthog">
<ResponseField name="apiKey" type="string matching ^phc\_" required>
Your PostHog API key.
Must match pattern: ^phc\_
</ResponseField>
<ResponseField name="apiHost" type="string (uri)">
Your PostHog API host.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="plausible" type="object">
Plausible analytics integration.
<Expandable title="Plausible">
<ResponseField name="domain" type="string" required>
Your Plausible domain.
</ResponseField>
<ResponseField name="server" type="string">
Your Plausible server.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="segment" type="object">
Segment integration.
<Expandable title="Segment">
<ResponseField name="key" type="string" required>
Your Segment key.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="telemetry" type="object">
Telemetry settings.
<Expandable title="Telemetry">
<ResponseField name="enabled" type="boolean">
Whether to enable telemetry.
<Note>
When set to `false`, feedback features are also disabled and do not appear on your documentation pages.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="cookies" type="object">
Cookie settings.
<Expandable title="Cookies">
<ResponseField name="key" type="string">
Key for cookies.
</ResponseField>
<ResponseField name="value" type="string">
Value for cookies.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Errors
<ResponseField name="errors" type="object">
Error handling settings.
<Expandable title="Errors">
<ResponseField name="404" type="object">
404 "Page not found" error handling.
<Expandable title="404">
<ResponseField name="redirect" type="boolean">
Whether to automatically redirect to the home page when a page is not found. Defaults to `true`.
</ResponseField>
<ResponseField name="title" type="string">
Custom title for the 404 error page.
</ResponseField>
<ResponseField name="description" type="string">
Custom description for the 404 error page. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
## Examples
<Tabs>
<Tab title="Basic example">
```json docs.json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "maple",
"name": "Example Co.",
"description": "Example Co. is a company that provides example content and placeholder text.",
"colors": {
"primary": "#3B82F6",
"light": "#F8FAFC",
"dark": "#0F172A"
},
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book",
"description": "How to use the Example Co. product",
"groups": [
{
"group": "Getting started",
"pages": [
"index",
"quickstart"
]
},
{
"group": "Customization",
"pages": [
"settings",
"users",
"features"
]
},
{
"group": "Billing",
"pages": [
"billing/overview",
"billing/payments",
"billing/subscriptions"
]
}
]
},
{
"dropdown": "Changelog",
"icon": "history",
"description": "Updates and changes",
"pages": [
"changelog"
]
}
]
},
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg",
"href": "https://example.com"
},
"navbar": {
"links": [
{
"label": "Community",
"href": "https://example.com/community"
}
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "https://example.com/start"
}
},
"footer": {
"socials": {
"x": "https://x.com/example",
"linkedin": "https://www.linkedin.com/company/example",
"github": "https://github.com/example",
"slack": "https://example.com/community"
},
"links": [
{
"header": "Resources",
"items": [
{
"label": "Customers",
"href": "https://example.com/customers"
},
{
"label": "Enterprise",
"href": "https://example.com/enterprise"
},
{
"label": "Request Preview",
"href": "https://example.com/preview"
}
]
},
{
"header": "Company",
"items": [
{
"label": "Careers",
"href": "https://example.com/careers"
},
{
"label": "Blog",
"href": "https://example.com/blog"
},
{
"label": "Privacy Policy",
"href": "https://example.com/legal/privacy"
}
]
}
]
},
"integrations": {
"ga4": {
"measurementId": "G-XXXXXXXXXX"
},
"telemetry": {
"enabled": true
},
"cookies": {
"key": "example_cookie_key",
"value": "example_cookie_value"
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
},
"errors": {
"404": {
"redirect": false,
"title": "I can't be found",
"description": "What ever **happened** to this _page_?"
}
}
}
```
</Tab>
<Tab title="Interactive API example">
```json docs.json {43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,72,73,74,75,76,77,78,79}
{
"$schema": "https://mintlify.com/docs.json",
"theme": "maple",
"name": "Example Co.",
"description": "Example Co. is a company that provides example content and placeholder text.",
"colors": {
"primary": "#3B82F6",
"light": "#F8FAFC",
"dark": "#0F172A"
},
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book",
"description": "How to use the Example Co. product",
"groups": [
{
"group": "Getting started",
"pages": [
"index",
"quickstart"
]
},
{
"group": "Customization",
"pages": [
"settings",
"users",
"features"
]
},
{
"group": "Billing",
"pages": [
"billing/overview",
"billing/payments",
"billing/subscriptions"
]
}
]
},
{
"dropdown": "API reference",
"icon": "terminal",
"description": "How to use the Example Co. API",
"groups": [
{
"group": "API reference",
"pages": [
"api-reference/introduction"
]
},
{
"group": "Endpoints",
"openapi": {
"source": "openapi.json"
}
}
]
},
{
"dropdown": "Changelog",
"icon": "history",
"description": "Updates and changes",
"pages": [
"changelog"
]
}
]
},
"api": {
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["javascript", "curl", "python"]
}
},
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg",
"href": "https://example.com"
},
"navbar": {
"links": [
{
"label": "Community",
"href": "https://example.com/community"
}
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "https://example.com/start"
}
},
"footer": {
"socials": {
"x": "https://x.com/example",
"linkedin": "https://www.linkedin.com/company/example",
"github": "https://github.com/example",
"slack": "https://example.com/community"
},
"links": [
{
"header": "Resources",
"items": [
{
"label": "Customers",
"href": "https://example.com/customers"
},
{
"label": "Enterprise",
"href": "https://example.com/enterprise"
},
{
"label": "Request Preview",
"href": "https://example.com/preview"
}
]
},
{
"header": "Company",
"items": [
{
"label": "Careers",
"href": "https://example.com/careers"
},
{
"label": "Blog",
"href": "https://example.com/blog"
},
{
"label": "Privacy Policy",
"href": "https://example.com/legal/privacy"
}
]
}
]
},
"integrations": {
"ga4": {
"measurementId": "G-XXXXXXXXXX"
},
"telemetry": {
"enabled": true
},
"cookies": {
"key": "example_cookie_key",
"value": "example_cookie_value"
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
},
"errors": {
"404": {
"redirect": false,
"title": "I can't be found",
"description": "What ever **happened** to this _page_?"
}
}
}
```
</Tab>
<Tab title="Multi-language example">
```json docs.json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "maple",
"name": "Example Co.",
"description": "Example Co. is a company that provides example content and placeholder text.",
"colors": {
"primary": "#3B82F6",
"light": "#F8FAFC",
"dark": "#0F172A"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "Documentation",
"href": "https://mintlify.com/docs"
},
{
"anchor": "Changelog",
"href": "https://mintlify.com/docs/changelog"
}
]
},
"languages": [ // [!code highlight:3]
{
"language": "en",
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book",
"description": "How to use the Example Co. product",
"pages": [
{
"group": "Getting started",
"pages": ["index", "quickstart"]
},
{
"group": "Customization",
"pages": ["settings", "users", "features"]
},
{
"group": "Billing",
"pages": [
"billing/overview",
"billing/payments",
"billing/subscriptions"
]
}
]
},
{
"dropdown": "Changelog",
"icon": "history",
"description": "Updates and changes",
"pages": ["changelog"]
}
]
},
{
"language": "es",// [!code highlight]
"dropdowns": [
{
"dropdown": "Documentación",
"icon": "book",
"description": "Cómo usar el producto de Example Co.",
"pages": [
{
"group": "Comenzando",
"pages": ["es/index", "es/quickstart"]
},
{
"group": "Personalización",
"pages": ["es/settings", "es/users", "es/features"]
},
{
"group": "Billing",
"pages": [
"es/billing/overview",
"es/billing/payments",
"es/billing/subscriptions"
]
}
]
},
{
"dropdown": "Changelog",
"icon": "history",
"description": "Actualizaciones y cambios",
"pages": ["es/changelog"]
}
]
}
]
},
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg",
"href": "https://example.com"
},
"navbar": {
"links": [
{
"label": "Community",
"href": "https://example.com/community"
}
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "https://example.com/start"
}
},
"footer": {
"socials": {
"x": "https://x.com/example",
"linkedin": "https://www.linkedin.com/company/example",
"github": "https://github.com/example",
"slack": "https://example.com/community"
},
"links": [
{
"header": "Resources",
"items": [
{
"label": "Customers",
"href": "https://example.com/customers"
},
{
"label": "Enterprise",
"href": "https://example.com/enterprise"
},
{
"label": "Request Preview",
"href": "https://example.com/preview"
}
]
},
{
"header": "Company",
"items": [
{
"label": "Careers",
"href": "https://example.com/careers"
},
{
"label": "Blog",
"href": "https://example.com/blog"
},
{
"label": "Privacy Policy",
"href": "https://example.com/legal/privacy"
}
]
}
]
},
"integrations": {
"ga4": {
"measurementId": "G-XXXXXXXXXX"
},
"telemetry": {
"enabled": true
},
"cookies": {
"key": "example_cookie_key",
"value": "example_cookie_value"
}
},
"contextual": {
"options": ["copy", "view", "chatgpt", "claude"]
},
"errors": {
"404": {
"redirect": false,
"title": "I can't be found",
"description": "What ever **happened** to this _page_?"
}
}
}
```
</Tab>
</Tabs>
## Upgrading from `mint.json`
If your docs project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`.
<Steps>
<Step title="Install or update the CLI">
If you haven't installed the [CLI](/installation), install it now:
<CodeGroup>
```bash npm
npm i -g mint
```
```bash yarn
yarn global add mint
```
```bash pnpm
pnpm add -g mint
```
</CodeGroup>
If you already have the CLI installed, make sure it is up to date:
```bash
mint update
```
</Step>
<Step title="Create your docs.json file">
In your docs repository, run:
```bash
mint upgrade
```
This command creates a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
</Step>
<Step title="Delete your mint.json file">
After verifying your `docs.json` is configured properly, you can safely delete your old `mint.json` file.
</Step>
</Steps>
Reference in New Issue View Git Blame Copy Permalink