diff --git a/settings/global.mdx b/settings/global.mdx
index 12b41588d..333c04b17 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -6,17 +6,21 @@ icon: "wrench"
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.
+
+ Install the [latest version](/development) and run `mintlify upgrade` for migration
+
+
## Properties
### Customization
-
+
The layout theme of the project
The name of the project, organization, or product
-
+
Minimum length: 1
@@ -28,6 +32,7 @@ Every documentation site requires a `docs.json` file that contains the core conf
The colors to use in your documentation. At the very least, you must define the primary color. For example:
+
```json
{
"colors": {
@@ -39,18 +44,20 @@ Every documentation site requires a `docs.json` file that contains the core conf
The primary color of the theme
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
+
+ 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})$
+
+ 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})$
+
+ Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})$
@@ -62,9 +69,11 @@ Every documentation site requires a `docs.json` file that contains the core conf
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`
@@ -73,12 +82,13 @@ Every documentation site requires a `docs.json` file that contains the core conf
Path pointing to the favicon file in your docs folder, including the file extension. The favicon will automatically be resized to the appropriate sizes
-The path to the favicon. Can be a single file or a pair for light and dark mode. Example: `/favicon.png`
+ The path to the favicon. 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`
@@ -89,13 +99,15 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Styling configurations
-
+
Whether corners are rounded or sharp. Defaults to `regular`.
-
+
+
The eyebrows style of the content. Defaults to `section`.
-
+
+
The codeblock theme. Defaults to `system`.
@@ -105,57 +117,65 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
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
-
+
+
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
-
+
+
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
-
+
+
The font format, can be one of woff, woff2
@@ -167,9 +187,10 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Light / dark mode toggle settings
-
+
The default light/dark mode. Defaults to system
+
Whether to hide the light / dark mode toggle. Defaults to `false`.
@@ -181,30 +202,31 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
-
-
-
-
+
+
+
-
+
+
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})$
+
+ 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})$
+
+ Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})$
@@ -221,20 +243,20 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The links in the navbar
-
-
+
+
A valid path or external link
-
+
-
-
-
-
+
+
+
+
A valid path or external link
@@ -252,89 +274,101 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
-
+
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
+
A valid path or 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
+
A valid path or 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})$
+
+ 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})$
+
+ 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
@@ -342,29 +376,29 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
Organizing by languages
-
+
Organizing by versions
-
+
Organizing by tabs
-
+
Organizing by anchors
-
+
Organizing by groups
-
+
An array of page paths or groups
-
@@ -375,32 +409,36 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
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
{
"x": "https://x.com/mintlify"
}
```
-
+
Valid property names: x, website, facebook, youtube, discord, slack, github, linkedin, instagram, hacker-news, medium, telegram, twitter
+
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
@@ -412,14 +450,12 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
-
-
-
-
-
-
+
+
+
+
+
@@ -434,25 +470,27 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
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
@@ -462,6 +500,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
Configurations for API pages generated from MDX files
@@ -470,16 +509,17 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Authentication configuration for the API
-
+
Authentication method for the API
+
Authentication name for the API
-
-
+
+
@@ -494,7 +534,8 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Meta tags added to every page. Must be a valid key-value pair
-
+
+
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`.
@@ -517,140 +558,122 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
-
-
+
-
+
-
-
+
-
+
-
-
+
-
+
-
Minimum length: 6
-
+
-
Must match pattern: ^G
-
+
-
Must match pattern: ^G
-
+
-
-
+
-
+
-
-
-
-
+
+
+
-
+
-
Minimum length: 6
-
+
-
Minimum length: 2
-
+
-
-
+
-
+
-
-
+
-
+
-
-
+
-
+
-
-
+
-
+
-
Must match pattern: ^phc\_
-
-
+
+
-
+
-
-
-
-
+
+
+
-
+
-
-
+
@@ -661,11 +684,17 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
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
@@ -681,9 +710,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
## `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)
+ 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
@@ -710,7 +737,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Where clicking on the logo links you to
-
@@ -749,7 +775,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
-
@@ -761,11 +786,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
[Prism](https://starter-prism.mintlify.app)
-
+
The global layout style of the documentation.
@@ -786,24 +807,24 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Custom fonts. Apply globally or set different fonts for headings and the body
text.
- Example:
+ Example:
- ```json
- "font": {
- "headings": {
- "family": "Roboto"
- },
- "body": {
- "family": "Oswald"
+ ```json
+ "font": {
+ "headings": {
+ "family": "Roboto"
+ },
+ "body": {
+ "family": "Oswald"
+ }
}
- }
- ```
+ ```
@@ -826,7 +847,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The font format. Required if using a custom font source (`url`).
-
@@ -858,7 +878,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
```
-
@@ -928,7 +947,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin
-
@@ -943,7 +961,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The url once you click on the button. Example: `https://mintlify.com/contact`
-
@@ -970,7 +987,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Whether to display the arrow
-
@@ -978,21 +994,21 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
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.
+ 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.
-
+
+ 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](/settings/versioning).
+ For more information, please refer to our
+ [versioning & localization documentation](/settings/versioning).
- Example:
+ Example:
```json Default
@@ -1011,7 +1027,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
}
]
```
-
@@ -1026,26 +1041,19 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
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.
- {" "}
+ {" "}
- 
+
- {" "}
+ {" "}
- 
+
@@ -1079,7 +1087,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
@@ -1099,27 +1106,26 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
An array of navigational tabs.
- Example:
+ Example:
- ```json
- "tabs": [
- {
- "name": "Writing Content",
- "url": "content"
- },
- {
- "name": "API References",
- "url": "api-playground"
- }
- ]
- ```
+ ```json
+ "tabs": [
+ {
+ "name": "Writing Content",
+ "url": "content"
+ },
+ {
+ "name": "API References",
+ "url": "api-playground"
+ }
+ ]
+ ```
@@ -1134,7 +1140,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
-
@@ -1142,27 +1147,27 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
An object to configure the footer with socials and links.
Example:
- ```json
- "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" }
- ]
- }
- ]
- }
- ```
+ ```json
+ "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" }
+ ]
+ }
+ ]
+ }
+ ```
@@ -1176,7 +1181,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Example: `https://x.com/mintlify`
-
@@ -1187,7 +1191,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
-
@@ -1200,17 +1203,16 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
- Enables a button to allow users to suggest edits via pull requests for public repositories.
+ 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.
-
+
+ If your docs repo is private, `suggestEdit` will not work.
+
Enables a button to allow users to raise an issue about the documentation
-
@@ -1306,7 +1308,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
-
@@ -1314,7 +1315,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
- Examples:
+ Examples:
```json Absolute
@@ -1328,7 +1329,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
```json Multiple
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
-
@@ -1345,7 +1345,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
-
@@ -1359,16 +1358,16 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
An array of paths you want to configure to permanently redirect to another path
- Example:
+ Example:
- ```json
- "redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
- }
- ]
- ```
+ ```json
+ "redirects": [
+ {
+ "source": "/source/path",
+ "destination": "/destination/path"
+ }
+ ]
+ ```
@@ -1382,7 +1381,6 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Example: `/destination`
-
@@ -1391,13 +1389,13 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Settings for Search Engine Optimization.
- Example:
+ Example:
- ```json
- "seo": {
- "indexHiddenPages": true
- }
- ```
+ ```json
+ "seo": {
+ "indexHiddenPages": true
+ }
+ ```
@@ -1478,4 +1476,4 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
}
```
-
+
\ No newline at end of file