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:
{
"$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 thedocs.json file.
Customization
required
The layout theme of your site.One of the following:
mint, maple, palm, willow, linden, almond, aspen, sequoia, luma.See Themes for more information.string
required
The name of your project, organization, or product.
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.
Show Colors
Show Colors
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
#.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
#.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
#.string
Description of your site for SEO and AI indexing.
string or object
Set your logo for both light and dark mode.
Show Logo
Show Logo
string
required
Path pointing to your logo file for light mode. Include the file extension. Example:
/logo.pngstring
required
Path pointing to your logo file for dark mode. Include the file extension. Example:
/logo-dark.pngstring (uri)
The URL to redirect to when clicking the logo. If not provided, the logo links to your homepage. Example:
https://mintlify.comstring 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.pngobject
Thumbnail customization for social media and page previews.
Show Thumbnails
Show Thumbnails
"light" | "dark"
The visual theme of your thumbnails. If not specified, thumbnails use your site’s color scheme defined by the
colors field.string
Background image for your thumbnails. Can be a relative path or absolute URL.
object
Font configuration for thumbnails. Only supports Google Fonts family names.
Show Fonts
Show Fonts
string
required
Font family name, such as “Open Sans” or “Playfair Display.” Supports Google Fonts family names.
object
Visual styling configurations.
Show Styling
Show Styling
"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.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
trueto force-load LaTeX stylesheets when automatic detection fails to recognize your mathematical expressions. - Set to
falseto prevent loading LaTeX stylesheets for improved performance if you don’t use mathematical expressions but have content that triggers false-positive detection.
"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
- Use a string to specify a single Shiki theme for all code blocks
- Use an object to specify separate Shiki themes for light and dark modes
string
A single Shiki theme name to use for both light and dark modes.
"styling": {
"codeblocks": {
"theme": "dracula"
}
}
object
object
Custom language configuration for code blocks.
Show languages
Show languages
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 used by Shiki.
"styling": {
"codeblocks": {
"languages": {
"custom": ["/languages/my-custom-language.json"]
}
}
}
object
Icon library settings.
Show Icons
Show Icons
"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.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.
object
Set custom fonts for your documentation. The default font varies by theme.
Show Fonts
Show Fonts
string
required
Font family, such as “Open Sans.” Supports Google Fonts family names.
number
Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
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.
family name, so no source URL is needed."woff" | "woff2"
Font file format. Required when using the
source field.object
Override font settings specifically for headings.
Show Heading
Show Heading
string
required
Font family, such as “Open Sans”, “Playfair Display.” Supports Google Fonts family names.
number
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
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.
family name, so no source URL is needed."woff" | "woff2"
Font file format. Required when using the
source field.object
Override font settings specifically for body text.
Show Body
Show Body
string
required
Font family, such as “Open Sans”, “Playfair Display.” Supports Google Fonts family names.
number
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
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.
family name, so no source URL is needed."woff" | "woff2"
Font file format. Required when using the
source field.object
object
Background color and decoration settings.
Show Background
Show Background
string or object
Background image for your site. Can be a single file or separate files for light and dark mode.
"gradient" | "grid" | "windows"
Background decoration for your theme.
object
object
Global variables for use throughout your documentation. Variables are replaced at build time using
{{variableName}} syntax.Show Variables
Show Variables
string
A key-value pair where the key is the variable name and the value is the replacement text. All variables referenced in your content must be defined, or the build fails. Variable names can contain alphanumeric characters, hyphens, and periods. Values are sanitized to prevent XSS attacks.
Structure
object
Navigation bar items to external links.
Show Navbar
Show Navbar
array of object
Links to display in the navbar
Show Links
Show Links
"github" | "discord"
Optional link type. Omit for a standard text link. Set to
github to link to a GitHub repository and display the repository’s star count. Set to discord to link to a Discord server and display the number of online users in the server.string
Text for the link. Required when
type is not set. Optional for github and discord types. When omitted, the label is automatically populated from API data (repository name for GitHub and server name for Discord).string (uri)
required
Link destination. Must be a valid external URL. For
github type, must be a GitHub repository URL. For discord type, must be a Discord invite URL.string
Optional icon name from the Lucide icon library
object
Primary button in the navbar.
Show Primary
Show Primary
"button" | "github" | "discord"
required
Button style. Choose
button for a standard button with a label, github for a link to a GitHub repository with live star count, or discord for a Discord server invite with live online user count.string
Button text. Required when
type is button. Optional for github and discord types—when omitted, the label is automatically populated from API data (repository name for GitHub, server name for Discord).string (uri)
required
Button destination. Must be an external URL. If
type is github, must be a GitHub repository URL. If type is discord, must be a Discord invite URL.object
required
The navigation structure of your content. See Navigation for detailed configuration options.
object
User interaction settings for navigation elements.
Show Interaction
Show Interaction
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.object
Metadata configuration for documentation pages.
object
Footer content and social media links.
Show Footer
Show Footer
object
Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example:Valid property names:
{
"x": "https://x.com/mintlify"
}
x, website, facebook, youtube, discord, slack, github, linkedin, instagram, hacker-news, medium, telegram, twitter, x-twitter, earth-americas, bluesky, threads, reddit, podcastobject
Site-wide banner displayed at the top of pages.
Show Banner
Show Banner
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:
{
"content": "🚀 Banner is live! [Learn more](mintlify.com)"
}
boolean
Whether to show the dismiss button on the right side of the banner. Defaults to
false.array of object
API configurations
object
API documentation and interactive playground settings.
Show api
Show api
string or array or object
OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
Show openapi
Show openapi
"openapi": "openapi.json"
"openapi": [
"openapi/v1.json",
"openapi/v2.json",
"https://api.example.com/openapi.yaml"
]
"openapi": {
"source": "openapi.json",
"directory": "api-docs"
}
string or array or object
AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
Show asyncapi
Show asyncapi
"asyncapi": "asyncapi.json"
"asyncapi": [
"asyncapi/events.yaml",
"asyncapi/webhooks.yaml",
"https://api.example.com/asyncapi.json"
]
"asyncapi": {
"source": "asyncapi.json",
"directory": "websockets"
}
object
Display settings for API parameters.
Show Params
Show Params
"all" | "closed"
Whether to expand all parameters by default. Defaults to
closed.object
object
Configurations for the autogenerated API examples.
Show Examples
Show Examples
array of string
Example languages for the autogenerated API snippets. Supported languages include:
bash(displayed as cURL)gojavajavascriptnode(displayed as Node.js)phppowershellpythonrubyswift
curl, golang, js, nodejs, rb, sh."required" | "all"
Whether to show optional parameters in API examples. Defaults to
all.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.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.object
Configurations for the OpenAPI spec.
Show Spec
Show Spec
boolean
Whether to show a download button for the OpenAPI spec on API reference pages. Defaults to
false.object
Configurations for API pages generated from MDX files.
Show Mdx
Show Mdx
object
string or array
Base URL prepended to relative paths in page-level
api frontmatter fields. Not used when the frontmatter contains a full URL.SEO and search
object
SEO indexing configurations.
Show Seo
Show Seo
object
Meta tags added to every page. Must be a valid key-value pair. See common meta tags reference for options.
"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.Integrations
object
Third-party integrations for analytics, chat, and tracking.
Show Integrations
Show Integrations
object
Google Analytics 4 integration.
Show Ga4
Show Ga4
string matching ^G
required
Your Google Analytics 4 measurement ID.Must match pattern: ^G
object
Errors
object
Error handling settings.
Show Errors
Show Errors
object
404 “Page not found” error handling.
Examples
- Basic example
- API documentation example
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"
]
}
]
}
]
},
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg",
"href": "https://example.com"
},
"footer": {
"socials": {
"x": "https://x.com/example",
"github": "https://github.com/example"
}
}
}
docs.json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "API Documentation",
"colors": {
"primary": "#10B981"
},
"api": {
"openapi": "openapi.json",
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["python", "javascript", "curl"]
}
},
"navigation": {
"groups": [
{
"group": "API Reference",
"openapi": {
"source": "openapi.json"
}
}
]
}
}