Configuration Reference Every documentation site requires a docs.json file that contains the core configuration settings.
This file controls everything from styling and navigation to integrations.
Customization One of the following: mint, maple, palm, willow, linden, almond. The layout theme of the project. Check out the Themes page for more information. The name of the project, organization, or product Minimum length: 1
Optional description used for SEO and LLM indexing
The colors to use in your documentation. At the very least, you must define the primary color. For example: { "colors" : { "primary" : "#ff0000" } } primary
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
required
The primary color of the theme Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
light
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The light color of the theme. Used for dark mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
dark
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The dark color of the theme. Used for light mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
The logo (for both light and dark mode) Path pointing to the light logo file to use in dark mode, including the file extension. Example: /logo.png
Path pointing to the dark logo file to use in light mode, including the file extension. Example: /logo-dark.png
The URL to redirect to when clicking the logo. If not provided, the logo will link to the homepage. Example: https://example.com
The path to your favicon file in the docs folder, including the file extension. The file will automatically be resized to appropriate favicon sizes.
Can be a single file or a pair for light and dark mode. Example: /favicon.png Path pointing to the light favicon file to use in dark mode, including the file extension. Example: /favicon.png
Path pointing to the dark favicon file to use in light mode, including the file extension. Example: /favicon-dark.png
Styling configurations eyebrows
"section" | "breadcrumbs"
The eyebrows style of the content. Defaults to section.
The codeblock theme. Defaults to system.
Icon library settings library
"fontawesome" | "lucide"
required
The icon library to be used. Defaults to fontawesome.
The font family, such as “Open Sans”, “Playfair Display”
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font format, can be one of woff, woff2
The font family, such as “Open Sans”, “Playfair Display”
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font format, can be one of woff, woff2
The font family, such as “Open Sans”, “Playfair Display”
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font format, can be one of woff, woff2
Light / dark mode toggle settings default
"system" | "light" | "dark"
The default light/dark mode. Defaults to system
Whether to hide the light / dark mode toggle. Defaults to true.
Background color and decoration settings decoration
"gradient" | "grid" | "windows"
The background decoration of the theme
The colors of the background light
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in light mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
dark
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in dark mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
Structure Navbar content and settings The links in the navbar A valid path or external link
type
"button" | "github"
required
The label for the primary button. This only applies when type is set to button.
A valid path or external link. If type is set to github, this will be the URL to the repository.
The navigation structure of the content Add external links that will appear on all sections and pages irregardless of navigation nesting language
"en" | "cn" | "zh" | "zh-Hans" | "zh-Hant" | "es" | "fr" | "ja" | "jp" | "pt" | "pt-BR" | "de" | "ko" | "it" | "ru" | "id" | "ar" | "tr"
required
The name of the language in the ISO 639-1 format
Whether this language is the default language
Whether the current option is default hidden
A valid path or external link
The name of the version Minimum length: 1
Whether this version is the default version
Whether the current option is default hidden
The name of the tab Minimum length: 1
The icon to be displayed in the section
Whether the current option is default hidden
The name of the anchor Minimum length: 1
The icon to be displayed in the section
light
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in light mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
dark
string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in dark mode Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$
Whether the current option is default hidden
A valid path or external link
The name of the dropdown Minimum length: 1
The icon to be displayed in the section
Whether the current option is default hidden
pages
array of string or object
Footer configurations An object in which each key is the name of a social media platform, and each value is the url to your profile. For example: { "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 The links to be displayed in the footer The header title of the column Minimum length: 1
The links to be displayed in the column The label of the link Minimum length: 1
Banner configurations The content of the banner. This can be a string of text or a markdown string. For example: { "content" : "🚀 Banner is live! [Learn more](mintlify.com)" } Whether the banner is dismissible. Defaults to false.
options
array of "copy" | "view" | "chatgpt" | "claude"
required
The options to be displayed in the contextual menu. The first option is the default option.
copy: Copy the current page as markdown to the clipboardview: View the current page as markdown in a new tabchatgpt: Feed the current page to ChatGPTclaude: Feed the current page to Claude The contextual menu is only available on preview & production deployments.
API Configurations API reference configuration and playground settings openapi
string or array or object
A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s) no starting slash in the directory
asyncapi
string or array or object
A string or an array of strings of absolute or relative urls pointing to the AsyncAPI file(s) Configurations for the API playground display
"interactive" | "simple" | "none"
The display mode of the API playground. Defaults to interactive.
Whether to pass API requests through a proxy server. Defaults to true.
Configurations for the autogenerated API examples Example languages for the autogenerated API snippets
Whether to show optional parameters in api examples, defaults to all
Configurations for API pages generated from MDX files Authentication configuration for the API method
"bearer" | "basic" | "key" | "cobo"
Authentication method for the API
Authentication name for the API
SEO & Search SEO indexing configurations Meta tags added to every page. Must be a valid key-value pair. Possible options here Specify which pages to be indexed by search engines. Setting navigable indexes pages that are set in navigation, all indexes all pages. Defaults to navigable.
Search display settings The prompt to be displayed in the search bar placeholder
Integrations Configurations for official integrations measurementId
string matching ^G
required
Must match pattern: ^G
tagId
string matching ^G
required
Must match pattern: ^G
apiKey
string matching ^phc\_
required
Must match pattern: ^phc_
Errors Whether to redirect to the home page, if the page is not found
Best Practices When configuring your docs.json file, consider these best practices:
Keep the configuration organized by grouping related settings together
Use meaningful names for groups and pages in your navigation structure
Provide complete paths for all assets (logos, favicons, etc.)
Test your configuration in both light and dark modes
Verify all external links and integrations are correctly configured
Use appropriate color contrasts for accessibility
Configure SEO settings for better search engine visibility
Validation The docs.json file is validated against a JSON schema to ensure proper configuration. You can reference the schema by including:
{ "$schema" : "https://mintlify.com/docs.json" } 
