From 684348a8f1f65586f2173d2924b8bb070871ddc0 Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Wed, 29 Jan 2025 15:41:41 -0800
Subject: [PATCH 1/6] Add docs.json docs
---
mint.json | 6 +-
settings/docs-json.mdx | 680 +++++++++++++++++++++++++++++++++++++++++
settings/global.mdx | 3 +-
3 files changed, 686 insertions(+), 3 deletions(-)
create mode 100644 settings/docs-json.mdx
diff --git a/mint.json b/mint.json
index 7c9ef5c65..bc55b6cf1 100644
--- a/mint.json
+++ b/mint.json
@@ -61,7 +61,11 @@
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
},
- "settings/global",
+ {
+ "group": "Global Settings",
+ "icon": "Wrench",
+ "pages": ["settings/global", "settings/docs-json"]
+ },
"settings/navigation",
"migration"
]
diff --git a/settings/docs-json.mdx b/settings/docs-json.mdx
new file mode 100644
index 000000000..f5a21f6b7
--- /dev/null
+++ b/settings/docs-json.mdx
@@ -0,0 +1,680 @@
+---
+title: "docs.json"
+description: "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.
+
+## 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 for optimal quality and file size.
+
+
+
+ Path to the logo in light mode. For example: `/logo/light.svg`
+
+
+
+ Path to the logo in dark mode. For example: `/logo/dark.svg`
+
+
+
+ Target URL for when users click the logo
+
+
+
+
+
+ Path to the favicon image. For example: `/favicon.svg`
+
+
+
+ Hex color codes for your global theme
+
+
+
+ The primary color used for highlighted content, section headers, and accents in light mode
+
+
+
+ The primary color used for highlighted content, section headers, and accents in dark mode
+
+
+
+ The primary color used for important buttons
+
+
+
+
+### Navigation Structure
+
+
+ The navigation configuration defines how content is organized and displayed in your documentation. It supports a tabbed interface with nested groups and pages.
+
+
+
+ Array of top-level navigation tabs
+
+
+
+ The name of the tab
+
+
+
+ Array of content groups within the tab
+
+
+
+ Name of the group
+
+
+
+ Array of pages or nested groups within this group. Pages can be specified as strings (paths to markdown files) or as nested group configurations.
+
+
+
+ Name of the nested group
+
+
+
+ FontAwesome icon name for the nested group
+
+
+
+ Array of page paths within the nested group
+
+
+
+
+
+
+
+
+
+
+### Icon Types and Nested Navigation
+
+ Specifies the style of FontAwesome icons used in navigation. Supported values: "brands", "duotone", "light", "sharp-solid", "solid", "thin". This can be applied to any navigation item that supports icons.
+
+
+Navigation groups can be nested to any depth by including additional group configurations within the pages array. Each nested level can include its own icon and pages array
+
+### Header and Footer
+
+
+ Configuration for the top navigation bar
+
+
+
+ Array of links to display in the navbar
+
+
+
+ Text to display for the link
+
+
+
+ URL the link points to
+
+
+
+
+
+ Configuration for the primary call-to-action button
+
+
+
+ Type of button (e.g., "button")
+
+
+
+ Text to display on the button
+
+
+
+ URL the button links to
+
+
+
+
+
+
+
+ Configuration for the documentation footer
+
+
+
+ Social media links to display in the footer. Supports: x, linkedin, github, slack
+
+ Example:
+ ```json
+ "socials": {
+ "x": "https://x.com/company",
+ "github": "https://github.com/company"
+ }
+ ```
+
+
+
+ Grouped links to display in the footer
+
+
+
+ Header text for the link group
+
+
+
+ Array of links in this section
+
+
+
+ Text to display for the link
+
+
+
+ URL the link points to
+
+
+
+
+
+
+
+
+### Anchors and Navigation Markers
+
+
+ Array of navigation anchors that provide quick access to documentation sections
+
+
+
+ Display name for the anchor
+
+
+
+ FontAwesome icon name for the anchor
+
+
+
+ Hex color code or gradient configuration for the anchor icon background
+
+
+
+ Starting gradient color (hex)
+
+
+
+ Ending gradient color (hex)
+
+
+
+
+
+ URL or path that the anchor links to
+
+
+
+ Version tag to control anchor visibility
+
+
+
+ Whether the anchor is hidden by default
+
+
+
+ FontAwesome icon style to use
+
+
+
+
+
+ Configuration for the top-most navigation anchor
+
+
+
+ Display name for the top anchor
+
+
+
+ FontAwesome icon name
+
+
+
+ FontAwesome icon style
+
+
+
+
+### API Configuration
+
+
+ Configuration for API documentation features
+
+
+
+ Configuration for MDX-based API documentation
+
+
+
+ Base server URL for API endpoints
+
+
+
+ Authentication method (e.g., "bearer")
+
+
+
+
+
+
+### API Playground Configuration
+
+
+
+
+ Configuration for the API playground interface
+
+
+
+ Controls playground visibility and functionality:
+ - "show": Full interactive playground
+ - "simple": Display endpoint only
+ - "hide": Hide playground completely
+
+
+
+ Disable request proxying through documentation servers
+
+
+
+
+
+ Configuration for parameter fields display
+
+
+
+ Controls default expansion state of parameter fields
+
+
+
+
+
+ Configuration for request examples
+
+
+
+
+
+ Array of language identifiers determining the order and availability of code examples
+
+
+
+
+
+
+
+
+
+ URL(s) or path(s) to OpenAPI specification files. Can be a single string or array of strings for multiple specifications.
+
+
+### Theme and Styling
+
+
+ The theme name to use for the documentation. Default themes provide pre-configured styling options.
+
+
+
+ Configuration for the documentation background
+
+
+
+ Style of background decoration (e.g., "windows", "gradient")
+
+
+
+
+
+ Additional styling configurations
+
+
+
+ Controls the border radius style throughout the documentation
+
+
+
+ Controls the style of section markers or "eyebrows" in the documentation
+
+
+
+ Style configuration for code blocks (e.g., "system")
+
+
+
+
+### Analytics and Integrations
+
+
+ Third-party service integrations
+
+
+
+ Google Analytics 4 configuration
+
+
+
+ GA4 measurement ID
+
+
+
+
+
+ Koala analytics configuration
+
+
+
+ Koala public API key
+
+
+
+
+
+
+### Extended Integrations
+
+
+
+
+ Analytics integration configurations
+
+
+ Google Analytics 4
+ Amplitude Analytics
+ Clearbit Analytics
+ Fathom Analytics
+ Hotjar Analytics
+ LogRocket Analytics
+ Mixpanel Analytics
+ PostHog Analytics
+
+
+
+
+ Customer support integrations
+
+
+ Intercom App ID
+ Front Chat ID
+
+
+
+
+ Privacy management integrations
+
+
+ Osano configuration ID
+
+
+
+
+
+### Additional Configurations
+
+
+ Configure permanent redirects from old paths to new ones
+
+
+
+ Original path to redirect from
+
+
+
+ New path to redirect to
+
+
+
+
+
+ Customize sidebar appearance and behavior
+
+
+
+ Visual style of sidebar navigation items
+
+
+
+
+
+ Customize topbar appearance
+
+
+
+ Visual style of the top navigation bar
+
+
+
+
+## Example Configuration
+
+Here's a complete example of a `docs.json` configuration file:
+
+
+```json docs.json
+{
+ "$schema": "https://mintlify.com/docs.json",
+ "name": "Documentation",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg",
+ "href": "https://docs.example.com"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#0D9373",
+ "light": "#55D799",
+ "dark": "#0D9373"
+ },
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "Documentation",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": [
+ "quickstart",
+ {
+ "group": "Setup",
+ "icon": "gear",
+ "pages": ["installation", "configuration"]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ "navbar": {
+ "links": [
+ {
+ "label": "Community",
+ "href": "https://community.example.com"
+ }
+ ],
+ "primary": {
+ "type": "button",
+ "label": "Get Started",
+ "href": "/quickstart"
+ }
+ }
+}
+```
+
+
+## Advanced Configuration
+
+### Search & Feedback
+
+
+ Configuration for the documentation search functionality
+
+
+
+ The location of the search bar. Options: "top", "side"
+
+
+
+ Custom placeholder text for the search input
+
+
+
+
+
+ Settings for user feedback features
+
+
+
+ Enable thumbs up/down rating system for pages
+
+
+
+ Enable "Suggest Edit" button for pages
+
+
+
+
+### Layout and Display
+
+
+ Controls the overall layout of the documentation. Options: "default", "modern", "minimal"
+
+
+
+ Configuration for dark/light mode functionality
+
+
+
+ Default color mode for new visitors
+
+
+
+ Whether to hide the mode toggle button
+
+
+
+
+### Versioning
+
+
+ Configuration for documentation versioning and localization
+
+
+
+ Display name for the version
+
+
+
+ Language locale code (e.g., "en", "es", "fr")
+
+
+
+ Whether this version should be the default
+
+
+
+
+### Code Display
+
+
+ Configuration for code block display
+
+
+
+ Default color mode for code blocks
+
+
+
+ Enable line highlighting in code blocks
+
+
+
+
+### SEO
+
+
+ Search Engine Optimization settings
+
+
+
+ Whether to allow search engines to index pages not in navigation
+
+
+
+ Base URL for canonical links
+
+
+
+
+### Security
+
+
+ Security configurations for API documentation
+
+
+
+ Authentication type for API endpoints
+
+
+
+ Additional security configurations for API endpoints
+
+
+
+
+### Custom Scripts
+
+
+ Configuration for custom JavaScript and CSS
+
+
+
+ Path or URL to the script file
+
+
+
+ Type of script file
+
+
+
+ Whether to defer script loading
+
+
+
+
+## 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
+{
+ "$schema": "https://mintlify.com/docs.json"
+}
diff --git a/settings/global.mdx b/settings/global.mdx
index 350cb3c18..5b1c555a4 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -1,7 +1,6 @@
---
-title: "Global Settings"
+title: "mint.json"
description: "Customize your documentation using the mint.json file"
-icon: "wrench"
---
Every Mintlify site needs a `mint.json` file with the core configuration
From c3c3d18015866267c66d7f5d51bee51da09348d3 Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Fri, 31 Jan 2025 00:47:55 -0800
Subject: [PATCH 2/6] Address PR comments
---
mint.json | 6 +-
settings/docs-json.mdx | 680 --------------
settings/global.mdx | 1906 ++++++++++++++++++++++++++++------------
3 files changed, 1335 insertions(+), 1257 deletions(-)
delete mode 100644 settings/docs-json.mdx
diff --git a/mint.json b/mint.json
index bc55b6cf1..7c9ef5c65 100644
--- a/mint.json
+++ b/mint.json
@@ -61,11 +61,7 @@
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
},
- {
- "group": "Global Settings",
- "icon": "Wrench",
- "pages": ["settings/global", "settings/docs-json"]
- },
+ "settings/global",
"settings/navigation",
"migration"
]
diff --git a/settings/docs-json.mdx b/settings/docs-json.mdx
deleted file mode 100644
index f5a21f6b7..000000000
--- a/settings/docs-json.mdx
+++ /dev/null
@@ -1,680 +0,0 @@
----
-title: "docs.json"
-description: "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.
-
-## 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 for optimal quality and file size.
-
-
-
- Path to the logo in light mode. For example: `/logo/light.svg`
-
-
-
- Path to the logo in dark mode. For example: `/logo/dark.svg`
-
-
-
- Target URL for when users click the logo
-
-
-
-
-
- Path to the favicon image. For example: `/favicon.svg`
-
-
-
- Hex color codes for your global theme
-
-
-
- The primary color used for highlighted content, section headers, and accents in light mode
-
-
-
- The primary color used for highlighted content, section headers, and accents in dark mode
-
-
-
- The primary color used for important buttons
-
-
-
-
-### Navigation Structure
-
-
- The navigation configuration defines how content is organized and displayed in your documentation. It supports a tabbed interface with nested groups and pages.
-
-
-
- Array of top-level navigation tabs
-
-
-
- The name of the tab
-
-
-
- Array of content groups within the tab
-
-
-
- Name of the group
-
-
-
- Array of pages or nested groups within this group. Pages can be specified as strings (paths to markdown files) or as nested group configurations.
-
-
-
- Name of the nested group
-
-
-
- FontAwesome icon name for the nested group
-
-
-
- Array of page paths within the nested group
-
-
-
-
-
-
-
-
-
-
-### Icon Types and Nested Navigation
-
- Specifies the style of FontAwesome icons used in navigation. Supported values: "brands", "duotone", "light", "sharp-solid", "solid", "thin". This can be applied to any navigation item that supports icons.
-
-
-Navigation groups can be nested to any depth by including additional group configurations within the pages array. Each nested level can include its own icon and pages array
-
-### Header and Footer
-
-
- Configuration for the top navigation bar
-
-
-
- Array of links to display in the navbar
-
-
-
- Text to display for the link
-
-
-
- URL the link points to
-
-
-
-
-
- Configuration for the primary call-to-action button
-
-
-
- Type of button (e.g., "button")
-
-
-
- Text to display on the button
-
-
-
- URL the button links to
-
-
-
-
-
-
-
- Configuration for the documentation footer
-
-
-
- Social media links to display in the footer. Supports: x, linkedin, github, slack
-
- Example:
- ```json
- "socials": {
- "x": "https://x.com/company",
- "github": "https://github.com/company"
- }
- ```
-
-
-
- Grouped links to display in the footer
-
-
-
- Header text for the link group
-
-
-
- Array of links in this section
-
-
-
- Text to display for the link
-
-
-
- URL the link points to
-
-
-
-
-
-
-
-
-### Anchors and Navigation Markers
-
-
- Array of navigation anchors that provide quick access to documentation sections
-
-
-
- Display name for the anchor
-
-
-
- FontAwesome icon name for the anchor
-
-
-
- Hex color code or gradient configuration for the anchor icon background
-
-
-
- Starting gradient color (hex)
-
-
-
- Ending gradient color (hex)
-
-
-
-
-
- URL or path that the anchor links to
-
-
-
- Version tag to control anchor visibility
-
-
-
- Whether the anchor is hidden by default
-
-
-
- FontAwesome icon style to use
-
-
-
-
-
- Configuration for the top-most navigation anchor
-
-
-
- Display name for the top anchor
-
-
-
- FontAwesome icon name
-
-
-
- FontAwesome icon style
-
-
-
-
-### API Configuration
-
-
- Configuration for API documentation features
-
-
-
- Configuration for MDX-based API documentation
-
-
-
- Base server URL for API endpoints
-
-
-
- Authentication method (e.g., "bearer")
-
-
-
-
-
-
-### API Playground Configuration
-
-
-
-
- Configuration for the API playground interface
-
-
-
- Controls playground visibility and functionality:
- - "show": Full interactive playground
- - "simple": Display endpoint only
- - "hide": Hide playground completely
-
-
-
- Disable request proxying through documentation servers
-
-
-
-
-
- Configuration for parameter fields display
-
-
-
- Controls default expansion state of parameter fields
-
-
-
-
-
- Configuration for request examples
-
-
-
-
-
- Array of language identifiers determining the order and availability of code examples
-
-
-
-
-
-
-
-
-
- URL(s) or path(s) to OpenAPI specification files. Can be a single string or array of strings for multiple specifications.
-
-
-### Theme and Styling
-
-
- The theme name to use for the documentation. Default themes provide pre-configured styling options.
-
-
-
- Configuration for the documentation background
-
-
-
- Style of background decoration (e.g., "windows", "gradient")
-
-
-
-
-
- Additional styling configurations
-
-
-
- Controls the border radius style throughout the documentation
-
-
-
- Controls the style of section markers or "eyebrows" in the documentation
-
-
-
- Style configuration for code blocks (e.g., "system")
-
-
-
-
-### Analytics and Integrations
-
-
- Third-party service integrations
-
-
-
- Google Analytics 4 configuration
-
-
-
- GA4 measurement ID
-
-
-
-
-
- Koala analytics configuration
-
-
-
- Koala public API key
-
-
-
-
-
-
-### Extended Integrations
-
-
-
-
- Analytics integration configurations
-
-
- Google Analytics 4
- Amplitude Analytics
- Clearbit Analytics
- Fathom Analytics
- Hotjar Analytics
- LogRocket Analytics
- Mixpanel Analytics
- PostHog Analytics
-
-
-
-
- Customer support integrations
-
-
- Intercom App ID
- Front Chat ID
-
-
-
-
- Privacy management integrations
-
-
- Osano configuration ID
-
-
-
-
-
-### Additional Configurations
-
-
- Configure permanent redirects from old paths to new ones
-
-
-
- Original path to redirect from
-
-
-
- New path to redirect to
-
-
-
-
-
- Customize sidebar appearance and behavior
-
-
-
- Visual style of sidebar navigation items
-
-
-
-
-
- Customize topbar appearance
-
-
-
- Visual style of the top navigation bar
-
-
-
-
-## Example Configuration
-
-Here's a complete example of a `docs.json` configuration file:
-
-
-```json docs.json
-{
- "$schema": "https://mintlify.com/docs.json",
- "name": "Documentation",
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg",
- "href": "https://docs.example.com"
- },
- "favicon": "/favicon.svg",
- "colors": {
- "primary": "#0D9373",
- "light": "#55D799",
- "dark": "#0D9373"
- },
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Setup",
- "icon": "gear",
- "pages": ["installation", "configuration"]
- }
- ]
- }
- ]
- }
- ]
- },
- "navbar": {
- "links": [
- {
- "label": "Community",
- "href": "https://community.example.com"
- }
- ],
- "primary": {
- "type": "button",
- "label": "Get Started",
- "href": "/quickstart"
- }
- }
-}
-```
-
-
-## Advanced Configuration
-
-### Search & Feedback
-
-
- Configuration for the documentation search functionality
-
-
-
- The location of the search bar. Options: "top", "side"
-
-
-
- Custom placeholder text for the search input
-
-
-
-
-
- Settings for user feedback features
-
-
-
- Enable thumbs up/down rating system for pages
-
-
-
- Enable "Suggest Edit" button for pages
-
-
-
-
-### Layout and Display
-
-
- Controls the overall layout of the documentation. Options: "default", "modern", "minimal"
-
-
-
- Configuration for dark/light mode functionality
-
-
-
- Default color mode for new visitors
-
-
-
- Whether to hide the mode toggle button
-
-
-
-
-### Versioning
-
-
- Configuration for documentation versioning and localization
-
-
-
- Display name for the version
-
-
-
- Language locale code (e.g., "en", "es", "fr")
-
-
-
- Whether this version should be the default
-
-
-
-
-### Code Display
-
-
- Configuration for code block display
-
-
-
- Default color mode for code blocks
-
-
-
- Enable line highlighting in code blocks
-
-
-
-
-### SEO
-
-
- Search Engine Optimization settings
-
-
-
- Whether to allow search engines to index pages not in navigation
-
-
-
- Base URL for canonical links
-
-
-
-
-### Security
-
-
- Security configurations for API documentation
-
-
-
- Authentication type for API endpoints
-
-
-
- Additional security configurations for API endpoints
-
-
-
-
-### Custom Scripts
-
-
- Configuration for custom JavaScript and CSS
-
-
-
- Path or URL to the script file
-
-
-
- Type of script file
-
-
-
- Whether to defer script loading
-
-
-
-
-## 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
-{
- "$schema": "https://mintlify.com/docs.json"
-}
diff --git a/settings/global.mdx b/settings/global.mdx
index 5b1c555a4..9cec3602e 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -1,807 +1,1569 @@
---
-title: "mint.json"
-description: "Customize your documentation using the mint.json file"
+title: "Global Settings"
+description: "Configure your documentation using the `docs.json` file"
+icon: "wrench"
---
-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 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.
## Properties
-### Styling
+### Customization
+
+
+ The layout theme of the project
+
- Name of your company or project. Used for the global title.
+ The name of the project, organization, or product
+
+ Minimum length: 1
-
- 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.
+
+ Optional description used for SEO and LLM indexing
+
-
-
- Path to the logo in light mode. For example: `/path/to/logo.svg`
+### Styling
+
+
+ The colors to use in your documentation. At the very least, you must define the primary color. For example: `{ "colors": { "primary": "#ff0000" } }`
+
+ No additional properties allowed
+
+
+
+ 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})$
+
+
+
-
- Path to the logo in dark mode. For example: `/path/to/logo.svg`
+
+ 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`
+
+
+
-
- Where clicking on the logo links you to
+
+ 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`
+
+
+
+ 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
+
+ No additional properties allowed
+
+
+ Whether corners are rounded or sharp. Defaults to `regular`.
+
+
+ The eyebrows style of the content. Defaults to `section`.
+
+
+ The codeblock theme. Defaults to `system`.
+
-
- Path to the favicon image. For example: `/path/to/favicon.svg`
+
+ Icon library settings
+
+ No additional properties allowed
+
+
+
+ The icon library to be used. Defaults to `fontawesome`.
+
+
-
- Hex color codes for your global theme
+
-
-
- The primary color. Used most often for highlighted content, section
- headers, accents, in light mode
+
+
+ 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
+
+
+
+ No additional properties allowed
+
+
+
+ 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
+
+
+
+
+ No additional properties allowed
-
- The primary color for dark mode. Used most often for highlighted content,
- section headers, accents, in dark mode
+
+
+ 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
+
+
+
+
+
+
+ Light / dark mode toggle settings
+
+ No additional properties allowed
-
- The primary color for important buttons
+
+
+ The default light/dark mode. Defaults to system
+
+ Whether to hide the light / dark mode toggle. Defaults to `false`.
+
+
+
+
+
+ Background color and decoration settings
+
+ No additional properties allowed
-
- 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
-
+
+ The background decoration of the theme
+
+
+ The colors of the background
+
+ No additional properties allowed
+
+
+
+ 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})$
+
+
+
-
- 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)
-
+### Structure
-
- The global layout style of the documentation.
-
+
+ Navbar content and settings
+
+ No additional properties allowed
-
- Set a decorative background.
+
+
+ The links in the navbar
-
-
- The style of the decorative background.
+
+
+
+
+ A valid path or external link
+
+
+
+
+
+
+
+
+
+
+
+ A valid path or external link
+
+
-
- Set a custom background image to be displayed behind every page.
-
+
+ The navigation structure of the content
-
- Custom fonts. Apply globally or set different fonts for headings and the body
- text.
+
+
+ Add external links that will appear on all sections and pages irregardless of navigation nesting
+
+ No additional properties allowed
-Example:
+
+
-```json
-"font": {
- "headings": {
- "family": "Roboto"
- },
- "body": {
- "family": "Oswald"
- }
-}
-```
+
+
+ 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 font family name. Custom fonts and all [Google
- Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans",
- "Playfair Display"
-
+
+
+ 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 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 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 URL to the font file. Can be used to specify a font that is not from
- Google Fonts.
-
+
+
+ The name of the dropdown
+
+ 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 font format. Required if using a custom font source (`url`).
+
+
+ The name of the anchor
+
+ Minimum length: 1
+
+
+ The icon to be displayed in the section
+
+
+
+ No additional properties allowed
+
+
+
+ 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
-
- Customize the dark mode toggle.
+
+
+
+
+ Organizing by tabs
-
-
- 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.
+
+
+
+ Organizing by dropdowns
-
- 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:
+
+
+
+
+ Organizing by anchors
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
+
+
+
+
+ Organizing by groups
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
- }
- ```
-
+
+
+
+ An array of page paths or groups
+
+
+
-
- Customize the styling of components within the sidebar.
+
+ Footer configurations
+
+ No additional properties allowed
-
-
- The styling of the navigation item.
+
+
+ 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
+
+
+ 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
+
+
+
+
-
- Styling configurations for the topbar.
+
-
-
- The styling of the navigation item.
+
+
+
+
+
+
-
- The location options for the search bar.
+### API Configurations
-
-
- The location of the search bar.
+
+ API reference configuration and playground settings
+
+ No additional properties allowed
+
+
+
+ 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
+
+ No additional properties allowed
+
+
+
+ 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
+
+ No additional properties allowed
+
+
+
+ Example languages for the autogenerated API snippets
+
+
+
+
+ Configurations for API pages generated from MDX files
+
+ No additional properties allowed
+
+
+
+ Authentication method for the API
+
+
+
+
-
- The style of the rounded edges.
+### SEO & Search
+
+
+ SEO indexing configurations
+
+ No additional properties allowed
+
+
+
+ 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`.
+
+
-
- The style of the code block.
+
+ Search display settings
+
+ No additional properties allowed
-
-
- `auto` will automatically switch between light and dark mode based on the
- user's system preferences.
+
+
+ The prompt to be displayed in the search bar placeholder
-### Structure
+### Integrations
-
- An array of groups with all the pages within that group
+
+ Configurations for official integrations
+
+ No additional properties allowed
-
-
- The name of the group.
-
+
+
+
+ No additional properties allowed
-
- 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.
+
+
+
+
+
+
+ No additional properties allowed
-
- The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders.
+
+
+
+
+
+
+ No additional properties allowed
-
- The type of [Fontawesome](https://fontawesome.com/icons) icon. 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.
+
+
+ No additional properties allowed
+
+
+
+
+ Minimum length: 6
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+ Must match pattern: ^G
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+ Must match pattern: ^G
+
+
+
+
+ No additional properties allowed
-
- The url once you click on the button. Example: `https://mintlify.com/contact`
+
+
+
+
+
+
+ No additional properties allowed
-
-
+
+
+
+
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+ Minimum length: 6
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+ Minimum length: 2
+
+
+
+
+
+ No additional properties allowed
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided
- including the number of GitHub stars.
+
+
+
+
+
+
+ No additional properties allowed
-
- If type is a link: What the button links to. If type is a github: Link to
- the repository to load GitHub information from.
+
+
+
+
+
+
+ No additional properties allowed
-
- Text inside the button. Only required if type is a link.
+
+
+
+
+
+
+ No additional properties allowed
-
- The style of the button.
+
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+ Must match pattern: ^phc\_
+
+
+
+
+
+
+
+ No additional properties allowed
-
- Whether to display the arrow
+
+
+
+
+
+
+
+
+ No additional properties allowed
+
+
+
+
+
-
- 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.
+## Best Practices
-
- 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.
-
+When configuring your `docs.json` file, consider these best practices:
-For more information, please refer to our
-[versioning & localization documentation](/settings/versioning).
+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
-Example:
+## Validation
-
- ```json Default
- "versions": ["v1.0", "v1.1"]
- ```
+The `docs.json` file is validated against a JSON schema to ensure proper configuration. You can reference the schema by including:
- ```json Localization
- "versions": [
- {
- "name": "English",
- "locale": "en",
- },
- {
- "name": "Español",
- "locale": "es"
- }
- ]
- ```
+```json
+{
+ "$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.
-
-
- The version name.
-
+ Example:
-
- The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`.
-
+ ```json
+ "font": {
+ "headings": {
+ "family": "Roboto"
+ },
+ "body": {
+ "family": "Oswald"
+ }
+ }
+ ```
-
- 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.
-
+
+
+ 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
+ "modeToggle": {
+ "default": "dark",
+ "isHidden": true
+ }
+ ```
+
+ ```json Only Light Mode
+ "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 [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders.
+
+
+
+ The type of [Fontawesome](https://fontawesome.com/icons) icon. 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](/settings/versioning).
-
-
+ Example:
-
- An array of the anchors, includes the icon, color, and url.
+
+ ```json Default
+ "versions": ["v1.0", "v1.1"]
+ ```
+
+ ```json Localization
+ "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.
+
-
-
- The name of the anchor label.
+
+
- Example: `Community`
-
+
+ An array of the anchors, includes the icon, color, and url.
-
- The [Font Awesome](https://fontawesome.com/search?q=heart) 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.
-
+
+
+ The name of the anchor label.
-
- Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
-
+ Example: `Community`
+
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
+
+ The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
-
-
+ Example: `comments`
+
-
- Override the default configurations for the top-most anchor. Note: if you have
- tabs configured, this does not apply.
+
+ 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 name of the top-most anchor
-
+
+ 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.
+
-
- Font Awesome icon.
-
+
+ Used if you want to hide an anchor until the correct docs version is selected.
+
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
+
+ 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"
+
-
- An array of navigational tabs.
+
+
-Example:
+
+ Override the default configurations for the top-most anchor. Note: if you have
+ tabs configured, this does not apply.
-```json
-"tabs": [
- {
- "name": "Writing Content",
- "url": "content"
- },
- {
- "name": "API References",
- "url": "api-playground"
- }
-]
-```
+
+
+ The name of the top-most anchor
+
-
-
- The name of the tab label.
-
+
+ Font Awesome icon.
+
-
- 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.
-
+
+ One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
+
-
- Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
-
+
+
-
-
+
+ An array of navigational tabs.
-
- An object to configure the footer with socials and links.
Example:
-```json
-"footer": {
- "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
- "links": [
+ ```json
+ "tabs": [
{
- "title": "Column 1",
- "links": [
- { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
- ]
+ "name": "Writing Content",
+ "url": "content"
},
{
- "title": "Column 2",
- "links": [
- { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
- ]
+ "name": "API References",
+ "url": "api-playground"
}
]
-}
-```
+ ```
-
-
- One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`
+
+
+ The name of the tab label.
+
- Example: `x`
-
+
+ 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.
+
-
- The URL to the social platform.
+
+ Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
+
- Example: `https://x.com/mintlify`
-
+
+
-
+
+ An object to configure the footer with socials and links.
+ Example:
-
-
- Title of the column
-
+ ```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" }
+ ]
+ }
+ ]
+ }
+ ```
-
- The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
-
+
+
+ One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`
-
-
+ Example: `x`
+
-
- Configurations to enable feedback buttons
+
+ The URL to the social platform.
-
-
- Enables a rating system for users to indicate whether the page has been helpful
-
+ Example: `https://x.com/mintlify`
+
-
- 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.
-
-
+
+
+ Title of the column
+
-
- Enables a button to allow users to raise an issue about the documentation
-
+
+ The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
+
-
-
+
+
-
- Configurations to change the search prompt
+
+ Configurations to enable feedback buttons
-
-
- Set the prompt for the search bar. Default is `Search...`
-
-
-
+
+
+ Enables a rating system for users to indicate whether the page has been helpful
+
-### API Configurations
+
+ Enables a button to allow users to suggest edits via pull requests for public repositories.
-
- Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
+
+ If your docs repo is private, `suggestEdit` will not work.
+
+
-
-
- 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.
-
+
+ Enables a button to allow users to raise an issue about the documentation
+
-
-
-
- The authentication strategy used for all API endpoints.
-
+
+
-
- The name of the authentication parameter used in the API playground.
+
+ Configurations to change the search prompt
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
+
+
+ Set the prompt for the search bar. Default is `Search...`
+
+
+
-
- The default value that's designed to be a prefix for the authentication input field.
+ ### API Configurations
- E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
-
-
-
+
+ Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
-
- Configurations for the 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.
+
-
-
- Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
+
+
+
+ The authentication strategy used for all API endpoints.
+
- Learn more at the [playground guides](/api-playground)
-
+
+ The name of the authentication parameter used in the API playground.
-
- By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.
+ If method is `basic`, the format should be `[usernameName]:[passwordName]`
+
- Required for select request types, such as file uploads.
-
-
-
+
+ The default value that's designed to be a prefix for the authentication input field.
-
- Configurations for API requests
+ E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
+
+
+
-
-
- Configurations for the auto-generated API request examples
+
+ Configurations for the API playground
-
-
- 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`
-
-
-
-
-
+
+
+ Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
-
- Configurations for the param fields in the API Playground
+ Learn more at the [playground guides](/api-playground)
+
-
-
- The default expanded state of expandable options in the API playground.
+
+ By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.
- `"all"` - every expandable component is expanded
+ Required for select request types, such as file uploads.
+
+
+
- `"topLevel"` - every top-level expandable component is expanded
+
+ Configurations for API requests
- `"topLevelOneOfs"` - every top-level `oneOf` type is expanded
+
+
+ Configurations for the auto-generated API request examples
- `"none"` - every expandable component is closed (default behavior)
-
-
-
+
+
+ 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
-
- A string or an array of strings of URL(s) or relative path(s) pointing to your
- OpenAPI file.
+
+
+ The default expanded state of expandable options in the API playground.
-Examples:
+ `"all"` - every expandable component is expanded
-
- ```json Absolute
- "openapi": "https://example.com/openapi.json"
- ```
+ `"topLevel"` - every top-level expandable component is expanded
- ```json Relative
- "openapi": "/openapi.json"
- ```
+ `"topLevelOneOfs"` - every top-level `oneOf` type is expanded
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
+ `"none"` - every expandable component is closed (default behavior)
+
+
+
-
-
+
+
-### Integrations
+
+ A string or an array of strings of URL(s) or relative path(s) pointing to your
+ OpenAPI file.
-
- Configurations to add third-party integrations (excluding analytics integrations)
+ Examples:
-
-
- Enables Intercom widget on docs site. The value should be your Intercom App ID.
-
+
+ ```json Absolute
+ "openapi": "https://example.com/openapi.json"
+ ```
-
- Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
-
+ ```json Relative
+ "openapi": "/openapi.json"
+ ```
-
-
+ ```json Multiple
+ "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
+ ```
-
- Configurations to add third-party analytics integrations. See full list of
- supported analytics [here](/integrations/analytics/overview).
-
+
+
-### Redirects
+ ### Integrations
-
- An array of paths you want to configure to permanently redirect to another path
+
+ Configurations to add third-party integrations (excluding analytics integrations)
-Example:
+
+
+ Enables Intercom widget on docs site. The value should be your Intercom App ID.
+
-```json
-"redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
- }
-]
-```
+
+ Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
+
-
-
- The path that you want to redirect from.
+
+
- Example: `/source`
-
+
+ Configurations to add third-party analytics integrations. See full list of
+ supported analytics [here](/integrations/analytics/overview).
+
-
- The path that you want to redirect to.
+ ### Redirects
- Example: `/destination`
-
+
+ An array of paths you want to configure to permanently redirect to another path
-
-
+ Example:
-### Search Engine Optimization
+ ```json
+ "redirects": [
+ {
+ "source": "/source/path",
+ "destination": "/destination/path"
+ }
+ ]
+ ```
-
- Settings for Search Engine Optimization.
+
+
+ The path that you want to redirect from.
-Example:
+ Example: `/source`
+
-```json
-"seo": {
- "indexHiddenPages": true
-}
-```
+
+ The path that you want to redirect to.
-
-
- Enables indexing pages not included in `navigation`.
-
-
-
+ Example: `/destination`
+
+
+
+
-## Example `mint.json`
+ ### Search Engine Optimization
-Click on the following dropdown to view a sample configuration file
+
+ Settings for Search Engine Optimization.
+
+ Example:
-
```json
- {
- "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"
+ "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
+ {
+ "name": "Mintlify",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
},
- {
- "name": "Community",
- "icon": "comments",
- "color": "#2564eb",
- "url": "https://mintlify.com/community"
- }
- ],
- "navigation": [
- {
- "group": "Getting Started",
- "pages": ["introduction", "quickstart"]
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#16A34A",
+ "light": "#4ADE80",
+ "dark": "#166534"
},
- {
- "group": "API Components",
- "pages": ["api-playground/overview", "api-playground/configuration"]
+ "topbarLinks": [
+ {
+ "name": "Contact Us",
+ "url": "mailto:support@mintlify.com"
+ }
+ ],
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://mintlify.com/start"
},
- {
- "group": "Settings",
- "pages": ["settings/global", "settings/page"]
+ "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"
},
- {
- "group": "Analytics",
- "pages": ["analytics/posthog"]
+ "integrations": {
+ "intercom": "APP_ID",
+ "frontchat": "CHAT_ID"
}
- ],
- "footerSocials": {
- "github": "https://github.com/mintlify",
- "slack": "https://mintlify.com/community",
- "x": "https://x.com/mintlify"
- },
- "integrations": {
- "intercom": "APP_ID",
- "frontchat": "CHAT_ID"
}
- }
- ```
+ ```
+
-
-## More Customization
-
-Learn more about how to further customize your docs with custom CSS and JS in
-[Custom Scripts](https://mintlify.com/docs/advanced/custom/).
From b218a9608107e938726e6f5639894c47b3ac14c6 Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Fri, 31 Jan 2025 14:14:12 -0800
Subject: [PATCH 3/6] Code blocks instead of inline code
---
settings/global.mdx | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/settings/global.mdx b/settings/global.mdx
index 9cec3602e..f7e801293 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -27,7 +27,14 @@ Every documentation site requires a `docs.json` file that contains the core conf
### Styling
- The colors to use in your documentation. At the very least, you must define the primary color. For example: `{ "colors": { "primary": "#ff0000" } }`
+ The colors to use in your documentation. At the very least, you must define the primary color. For example:
+ ```json
+ {
+ "colors": {
+ "primary": "#ff0000"
+ }
+ }
+ ```
No additional properties allowed
@@ -428,7 +435,12 @@ 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: `{ "x": "https://x.com/mintlify" }`
+ 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
From 0038aac4431eb338053313075dc645f9a684dfdc Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Sun, 2 Feb 2025 19:49:20 -0800
Subject: [PATCH 4/6] Update based on schema changes
---
settings/global.mdx | 15 +++++++++++++--
1 file changed, 13 insertions(+), 2 deletions(-)
diff --git a/settings/global.mdx b/settings/global.mdx
index f7e801293..886c06c59 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -535,8 +535,19 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
No additional properties allowed
-
- Authentication method for the API
+
+ Authentication configuration for the API
+
+ No additional properties allowed
+
+
+
+ Authentication method for the API
+
+
+ Authentication name for the API
+
+
From 0d178c4aca7898eac296d9a3e4d74bfcf147ffb6 Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Mon, 3 Feb 2025 10:03:49 -0800
Subject: [PATCH 5/6] Remove 'No additional property allowed
---
settings/global.mdx | 74 ---------------------------------------------
1 file changed, 74 deletions(-)
diff --git a/settings/global.mdx b/settings/global.mdx
index 886c06c59..f7a7339b4 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -35,8 +35,6 @@ Every documentation site requires a `docs.json` file that contains the core conf
}
}
```
-
- No additional properties allowed
@@ -89,8 +87,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Styling configurations
-
- No additional properties allowed
@@ -107,8 +103,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Icon library settings
-
- No additional properties allowed
@@ -133,8 +127,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The font format, can be one of woff, woff2
-
- No additional properties allowed
@@ -152,8 +144,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -175,8 +165,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Light / dark mode toggle settings
-
- No additional properties allowed
@@ -190,8 +178,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Background color and decoration settings
-
- No additional properties allowed
@@ -208,8 +194,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The colors of the background
-
- No additional properties allowed
@@ -231,8 +215,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Navbar content and settings
-
- No additional properties allowed
@@ -267,8 +249,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Add external links that will appear on all sections and pages irregardless of navigation nesting
-
- No additional properties allowed
@@ -357,8 +337,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The icon to be displayed in the section
-
- No additional properties allowed
@@ -430,8 +408,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Footer configurations
-
- No additional properties allowed
@@ -488,8 +464,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
API reference configuration and playground settings
-
- No additional properties allowed
@@ -506,8 +480,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Configurations for the API playground
-
- No additional properties allowed
@@ -520,8 +492,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Configurations for the autogenerated API examples
-
- No additional properties allowed
@@ -531,14 +501,10 @@ 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
-
- No additional properties allowed
Authentication configuration for the API
-
- No additional properties allowed
@@ -560,8 +526,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
SEO indexing configurations
-
- No additional properties allowed
@@ -575,8 +539,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Search display settings
-
- No additional properties allowed
@@ -589,13 +551,9 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
Configurations for official integrations
-
- No additional properties allowed
-
- No additional properties allowed
@@ -603,8 +561,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -612,8 +568,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -621,8 +575,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -632,8 +584,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -643,8 +593,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -654,8 +602,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -663,8 +609,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -674,8 +618,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -685,8 +627,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -696,8 +636,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -705,8 +643,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -714,8 +650,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -723,8 +657,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -732,8 +664,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -745,8 +675,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
@@ -756,8 +684,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
- No additional properties allowed
From 81b0eb63be57e71126de2b6819594ce8dceca472 Mon Sep 17 00:00:00 2001
From: Ricardo Nunez <113212961+ricardonunez-io@users.noreply.github.com>
Date: Mon, 3 Feb 2025 10:51:41 -0800
Subject: [PATCH 6/6] Cleanup
---
settings/global.mdx | 37 -------------------------------------
1 file changed, 37 deletions(-)
diff --git a/settings/global.mdx b/settings/global.mdx
index f7a7339b4..0d8f31897 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -306,25 +306,6 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
-
-
-
- The name of the dropdown
-
- Minimum length: 1
-
-
- The icon to be displayed in the section
-
-
- Whether the current option is default hidden
-
-
- A valid path or external link
-
-
-
@@ -364,44 +345,26 @@ 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 dropdowns
-
-
-
Organizing by anchors
-
-
Organizing by groups
-
-
An array of page paths or groups
-
-