Every Mintlify site needs a docs.json file with the core configuration settings. This file controls everything from your project name and logo to navigation structure, colors, and API configurations.
The docs.json file should be placed in the root of your documentation directory.
Properties Basic configuration Name of your project. Used for the global title that appears in the browser tab and throughout your documentation. Example: mintlify
An array of groups with all the pages within that group. This is the core structure that defines your documentation’s navigation menu. The name of the group that appears in the sidebar. Example: Settings
The relative paths to the markdown files that will serve as pages. Do not include the .mdx extension. Example: ["customization", "page"]
Branding Path to logo image or object with path to “light” and “dark” mode logo images. You can provide different logos for light and dark mode to ensure optimal visibility. Path to the logo in light mode. Typically a darker logo that shows well on light backgrounds.
Path to the logo in dark mode. Typically a lighter logo that shows well on dark backgrounds.
Where clicking on the logo links you to. By default, links to the homepage.
Path to the favicon image that appears in the browser tab.
Theme colors Hex color codes for your global theme. These colors define the visual identity of your documentation. The primary color. Used most often for highlighted content, section headers, and accents in light mode.
The primary color for dark mode. Used most often for highlighted content, section headers, and accents in dark mode.
The primary color for important buttons and call-to-action elements.
The color of the background in both light and dark mode. The hex color code of the background in light mode.
The hex color code of the background in dark mode.
A background image to be displayed behind every page. This creates a branded experience throughout your documentation. See example implementations with Infisical and FRPC . Topbar configuration Array of names and urls of links you want to include in the topbar. These appear in the top right of your documentation. The name of the button that appears in the topbar. Example: Contact us
The url once you click on the button. Example: https://mintlify.com/docs
A prominent call-to-action button in the topbar. Can be a link or display GitHub repository information. Show Topbar Call to Action
type
"link" or "github"
default: "link"
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
If link: What the button links to. If github: Link to the repository to load GitHub information from.
Text inside the button. Only required if type is a link.
Navigation structure An array of navigational tabs. Tabs allow you to organize your documentation into major sections. The name of the tab label that appears in the navigation.
The start of the URL that marks what pages go in the tab. Generally, this is the name of the folder you put your pages in.
An array of the anchors, includes the icon, color, and url. Anchors are special navigation sections that appear prominently in your sidebar. The Font Awesome icon used to feature the anchor. Example: comments The name of the anchor label. Example: Community
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties from and to that are each a hex color.
Used if you want to hide an anchor until the correct docs version is selected.
Pass true if you want to hide the anchor until you directly link someone to docs inside it.
One of: “brands”, “duotone”, “light”, “sharp-solid”, “solid”, or “thin”
Override the default configurations for the top-most anchor. This is the first section that appears in your navigation. name
string
default: "Documentation"
The name of the top-most anchor.
icon
string
default: "book-open"
Font Awesome icon for the top anchor.
One of: “brands”, “duotone”, “light”, “sharp-solid”, “solid”, or “thin”
Versioning Array of version names. Only use this if you want to show different versions of docs with a dropdown in the navigation bar. Version management allows you to maintain multiple versions of your documentation simultaneously, useful for APIs with breaking changes.
API configuration Configuration for API settings. Learn more about API pages at API Components . The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
method
"bearer" | "basic" | "key"
The authentication strategy used for all API endpoints.
The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
The default value that’s designed to be a prefix for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
Configurations for the API playground that allows users to test API endpoints directly from your documentation. mode
"show" | "simple" | "hide"
default: "show"
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity simple. Learn more at the playground guides Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. This behavior will soon be enabled by default, at which point this field will be deprecated.
A string or an array of strings of URL(s) or relative path(s) pointing to your OpenAPI file. Mintlify can automatically generate API documentation from OpenAPI specifications. Examples: "openapi" : "https://example.com/openapi.json"
An object of social media accounts where the key:property pair represents the social media platform and the account url. Example: { "x" : "https://x.com/mintlify" , "website" : "https://mintlify.com" }
One of the following values: website, facebook, x, discord, slack, github, linkedin, instagram, hacker-news Example: x
The URL to the social platform. Example: https://x.com/mintlify
User feedback Configurations to enable feedback buttons that allow users to contribute to your documentation. Enables a button to allow users to suggest edits via pull requests.
Enables a button to allow users to raise an issue about the documentation.
Display preferences Customize the dark mode toggle and set default theme preferences for your documentation. Set if you always want to show light or dark mode for new users. When not set, we default to the same mode as the user’s operating system.
Set to true to hide the dark/light mode toggle. You can combine isHidden with default to force your docs to only use light or dark mode. For example: Only Dark Mode
Only Light Mode
"modeToggle" : { "default" : "dark" , "isHidden" : true }
Example configuration Here’s a complete example of a docs.json file with common settings:
{ "name" : "My Documentation" , "logo" : { "light" : "/logo/light.svg" , "dark" : "/logo/dark.svg" }, "favicon" : "/favicon.png" , "colors" : { "primary" : "#0D9373" , "light" : "#07C983" , "dark" : "#0D9373" }, "topbarLinks" : [ { "name" : "Contact" , "url" : "https://example.com/contact" } ], "topbarCtaButton" : { "type" : "github" , "url" : "https://github.com/example/repo" }, "navigation" : [ { "group" : "Getting Started" , "pages" : [ "quickstart" , "installation" ] } ], "footerSocials" : { "github" : "https://github.com/example" , "x" : "https://x.com/example" } }
You can validate your docs.json configuration by running mint dev and checking for any errors in the console.