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.
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}
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.
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
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.
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.
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.
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.
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.
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).
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.
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).
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.
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 for more information.
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)"}
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.
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.
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.
