> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Global Settings
> Configure your documentation using the `docs.json` file
Every documentation site requires a `docs.json` file that contains the core configuration settings. This file controls everything from styling and navigation to integrations and analytics.
If you're currently using the legacy `mint.json` configuration file, please update the CLI:
```sh theme={null}
npm i -g mintlify@latest
```
And run the new `upgrade` command in your docs repository:
```sh theme={null}
mintlify upgrade
```
This will generate a `docs.json` based off of your `mint.json`. Then, please delete the `mint.json` file from your repository.
## Properties
### Customization
The layout theme of the project. Examples:
[Maple](https://maple.mintlify.app/), [Palm](https://palm.mintlify.app/),
The name of the project, organization, or product Minimum length: 1
Optional description used for SEO and LLM indexing
### Styling
The colors to use in your documentation. At the very least, you must define the primary color. For example:
```json theme={null}
{
"colors": {
"primary": "#ff0000"
}
}
```
The primary color of the theme
Must match pattern: ^#(\[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]{6}|\[a-fA-F0-9]{3})\$
The dark color of the theme. Used for light mode
Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})\$
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
The eyebrows style of the content. Defaults to `section`.
The codeblock theme. Defaults to `system`.
Icon library settings
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 source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
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 source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
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 source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
The font format, can be one of woff, woff2
Light / dark mode toggle settings
The default light/dark mode. Defaults to system
Whether to hide the light / dark mode toggle. Defaults to `true`.
Background color and decoration settings
The background decoration of the theme
The colors of the background
The color in hex format to use in light mode
Must match pattern: ^#(\[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]{6}|\[a-fA-F0-9]{3})\$
### Structure
Navbar content and settings
The links in the navbar
A valid path or external link
A valid path or external link
The navigation structure of the content
Add external links that will appear on all sections and pages irregardless of navigation nesting
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
An external link
The name of the tab
Minimum length: 1
The icon to be displayed in the section
Whether the current option is default hidden
An external link
The name of the anchor
Minimum length: 1
The icon to be displayed in the section
The color in hex format to use in light mode
Must match pattern: ^#(\[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]{6}|\[a-fA-F0-9]{3})\$
Whether the current option is default hidden
A valid path or external link
Organizing by languages
Organizing by versions
Organizing by tabs
Organizing by anchors
Organizing by groups
An array of page paths or groups
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:
```json theme={null}
{
"x": "https://x.com/mintlify"
}
```
Valid property names: bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, twitter, website, x, youtube
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
The url of the link
Banner configurations
The content of the banner. This can be a string of text or a markdown string. For example:
```json theme={null}
{
"content": "🚀 Banner is live! [Learn more](mintlify.com)"
}
```
Whether the banner is dismissible. Defaults to `false`.
### API Configurations
API reference configuration and playground settings
A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s)
Minimum length: 1
Configurations for the API playground
The display mode of the API playground. Defaults to `interactive`.
Whether to pass API requests through a proxy server. Defaults to `false`.
Configurations for the autogenerated API examples
Example languages for the autogenerated API snippets
Configurations for API pages generated from MDX files
Authentication configuration for the API
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](https://mintlify.com/docs/settings/seo#supported-meta-tags)
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
Minimum length: 6
Must match pattern: ^G
Must match pattern: ^G
Minimum length: 6
Minimum length: 2
Must match pattern: ^phc\_
## Best Practices
When configuring your `docs.json` file, consider these best practices:
1. Keep the configuration organized by grouping related settings together
2. Use meaningful names for groups and pages in your navigation structure
3. Provide complete paths for all assets (logos, favicons, etc.)
4. Test your configuration in both light and dark modes
5. Verify all external links and integrations are correctly configured
6. Use appropriate color contrasts for accessibility
7. 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:
```json theme={null}
{
"$schema": "https://mintlify.com/docs.json"
}
```
## `mint.json` (Legacy)
Every Mintlify site needs a `mint.json` file with the core configuration
settings. Learn more about the [properties](#properties) or from an
[example](#example-mint-json)
## Properties
### Styling
{" "}
Name of your company or project. Used for the global title.
Path to logo image or object with path to "light" and "dark" mode logo images,
and where the logo links to. SVG format is recommended. It does not pixelate
and the file size is generally smaller.
Path to the logo in light mode. For example: `/path/to/logo.svg`
Path to the logo in dark mode. For example: `/path/to/logo.svg`
Where clicking on the logo links you to
{" "}
Path to the favicon image. For example: `/path/to/favicon.svg`
Hex color codes for your global theme
The primary color. Used most often for highlighted content, section
headers, accents, in light mode
The primary color for dark mode. Used most often for highlighted content,
section headers, accents, in dark mode
The primary color for important buttons
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 preset theme configuration that changes the look and feel of the project. A
theme is a set of default styling configurations. Examples:
[Venus](https://starter-venus.mintlify.app),
[Quill](https://starter-quill.mintlify.app),
[Prism](https://starter-prism.mintlify.app)
{" "}
The global layout style of the documentation.
Set a decorative background.
The style of the decorative background.
{" "}
Set a custom background image to be displayed behind every page.
Custom fonts. Apply globally or set different fonts for headings and the body
text.
Example:
```json theme={null}
"font": {
"headings": {
"family": "Roboto"
},
"body": {
"family": "Oswald"
}
}
```
The font family name. Custom fonts and all [Google
Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans",
"Playfair Display"
The font weight. Precise values such as `560` are also supported for
variable fonts. Check under the Styles section for your Google Font for
the available weights.
The URL to the font file. Can be used to specify a font that is not from
Google Fonts.
The font format. Required if using a custom font source (`url`).
Customize the dark mode toggle.
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:
```json Only Dark Mode theme={null}
"modeToggle": {
"default": "dark",
"isHidden": true
}
```
```json Only Light Mode theme={null}
"modeToggle": {
"default": "light",
"isHidden": true
}
```
Customize the styling of components within the sidebar.
The styling of the navigation item.
Styling configurations for the topbar.
The styling of the navigation item.
The location options for the search bar.
The location of the search bar.
{" "}
The style of the rounded edges.
The style of the code block.
`auto` will automatically switch between light and dark mode based on the
user's system preferences.
### Structure
An array of groups with all the pages within that group
The name of the group.
The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
The [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon for the group. Note: this only applies to sub-folders.
The type of icon (only for [Font Awesome](https://fontawesome.com/icons) icons). Must be one of: brands, duotone, light, sharp-solid, solid, thin
Array of names and urls of links you want to include in the topbar
The name of the button.
The url once you click on the button. Example: `https://mintlify.com/contact`
Link shows a button. GitHub shows the repo information at the url provided
including the number of GitHub stars.
If type is a link: What the button links to. If type is a github: Link to
the repository to load GitHub information from.
Text inside the button. Only required if type is a link.
The style of the button.
Whether to display the arrow
Array of version names. Only use this if you want to show different versions
of docs with a dropdown in the navigation bar.
Versions can be leveraged for localization. You can store translated content
under a version, and once you specify the `locale` any fixed text in Mintlify,
such as 'Was this page helpful?', will automatically be translated based on the
locale. We currently support localization in English, Chinese, Spanish, French,
Japanese, and Portuguese.
{" "}
Localization auto-translates the UI and fixed assets in the docs, such as "Was
this page helpful?". You must translate the content of the pages yourself.
For more information, please refer to our
[versioning & localization documentation](/navigation/versions).
Example:
```json Default theme={null}
"versions": ["v1.0", "v1.1"]
```
```json Localization theme={null}
"versions": [
{
"name": "English",
"locale": "en",
},
{
"name": "Español",
"locale": "es"
}
]
```
The version name.
The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`.
Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version.
An array of the anchors, includes the icon, color, and url.
{" "}
{" "}
{" "}
{" "}
The name of the anchor label.
Example: `Community`
The [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon used to feature the anchor.
Example: `comments`
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. Note: if you have
tabs configured, this does not apply.
The name of the top-most anchor
Font Awesome icon.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
An array of navigational tabs.
Example:
```json theme={null}
"tabs": [
{
"name": "Writing Content",
"url": "content"
},
{
"name": "API References",
"url": "api-playground"
}
]
```
The name of the tab label.
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.
Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
An object to configure the footer with socials and links.
Example:
```json theme={null}
"footer": {
"socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
"links": [
{
"title": "Column 1",
"links": [
{ "label": "Column 1 Link 1", "url": "https://mintlify.com" },
{ "label": "Column 1 Link 2", "url": "https://mintlify.com" }
]
},
{
"title": "Column 2",
"links": [
{ "label": "Column 2 Link 1", "url": "https://mintlify.com" },
{ "label": "Column 2 Link 2", "url": "https://mintlify.com" }
]
}
]
}
```
One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`
Example: `x`
The URL to the social platform.
Example: `https://x.com/mintlify`
Title of the column
The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
Configurations to enable feedback buttons
Enables a rating system for users to indicate whether the page has been helpful
Enables a button to allow users to suggest edits via pull requests for public repositories.
If your docs repo is private, `suggestEdit` will not work.
Enables a button to allow users to raise an issue about the documentation
Configurations to change the search prompt
Set the prompt for the search bar. Default is `Search...`
### API Configurations
Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
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.
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
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
Learn more at the [playground guides](/api-playground)
By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.
Required for select request types, such as file uploads.
Configurations for API requests
Configurations for the auto-generated API request examples
An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java`
Configurations for the param fields in the API Playground
The default expanded state of expandable options in the API playground.
`"all"` - every expandable component is expanded
`"topLevel"` - every top-level expandable component is expanded
`"topLevelOneOfs"` - every top-level `oneOf` type is expanded
`"none"` - every expandable component is closed (default behavior)
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
Examples:
```json Absolute theme={null}
"openapi": "https://example.com/openapi.json"
```
```json Relative theme={null}
"openapi": "/openapi.json"
```
```json Multiple theme={null}
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
### Integrations
Configurations to add third-party integrations (excluding analytics integrations)
Enables Intercom widget on docs site. The value should be your Intercom App ID.
Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
Configurations to add third-party analytics integrations. See full list of
supported analytics [here](/integrations/analytics/overview).
### Redirects
An array of paths you want to configure to permanently redirect to another path
Example:
```json theme={null}
"redirects": [
{
"source": "/source/path",
"destination": "/destination/path"
}
]
```
The path that you want to redirect from.
Example: `/source`
The path that you want to redirect to.
Example: `/destination`
### Search Engine Optimization
Settings for Search Engine Optimization.
Example:
```json theme={null}
"seo": {
"indexHiddenPages": true
}
```
Enables indexing pages not included in `navigation`.
## Example `mint.json`
Click on the following dropdown to view a sample configuration file
```json theme={null}
{
"name": "Mintlify",
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
},
"favicon": "/favicon.svg",
"colors": {
"primary": "#16A34A",
"light": "#4ADE80",
"dark": "#166534"
},
"topbarLinks": [
{
"name": "Contact Us",
"url": "mailto:support@mintlify.com"
}
],
"topbarCtaButton": {
"name": "Get Started",
"url": "https://mintlify.com/start"
},
"anchors": [
{
"name": "API Components",
"icon": "rectangle-terminal",
"color": "#f59f0b",
"url": "api-components"
},
{
"name": "Community",
"icon": "comments",
"color": "#2564eb",
"url": "https://mintlify.com/community"
}
],
"navigation": [
{
"group": "Getting Started",
"pages": ["introduction", "quickstart"]
},
{
"group": "API Components",
"pages": ["api-playground/overview", "api-playground/configuration"]
},
{
"group": "Settings",
"pages": ["settings/global", "settings/page"]
},
{
"group": "Analytics",
"pages": ["analytics/posthog"]
}
],
"footerSocials": {
"github": "https://github.com/mintlify",
"slack": "https://mintlify.com/community",
"x": "https://x.com/mintlify"
},
"integrations": {
"intercom": "APP_ID",
"frontchat": "CHAT_ID"
}
}
```