mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
ec7e679407
* Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> * Update organize/settings.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> * Update api-playground/overview.mdx * Update organize/settings.mdx --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
1673 lines
56 KiB
Plaintext
1673 lines
56 KiB
Plaintext
---
|
|
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=""woff" | "woff2"">
|
|
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=""woff" | "woff2"">
|
|
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">
|
|
Server configuration for API requests.
|
|
</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> |