From d447c105fa221f56fccdadac650951bd9f03feb7 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 10 Jun 2025 14:53:06 -0700 Subject: [PATCH 01/17] update intro --- settings.mdx | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/settings.mdx b/settings.mdx index c3af97200..a094769ca 100644 --- a/settings.mdx +++ b/settings.mdx @@ -4,13 +4,47 @@ description: "Configure the global settings for your documentation" icon: "settings-2" --- -Every documentation site requires a **docs.json** file. +Your `docs.json` file turns a collection of Markdown files into a navigable, customized documentation site. This configuration file is required for every documentation site and controls everything from styling and navigation to integrations. -This file contains the global configuration settings and controls everything from styling and navigation to integrations. +Settings in `docs.json` apply to all pages globally. Changes to your `docs.json` take effect when your site builds. + +## Configuring settings + +TODO: + +Required vs optional settings + +Minimal working configuration example + +Most impactful settings to begin with (name, colors, navigation) + +Configuration patterns +Possibly four tabbed examples: +- Basic documentation site setup +- API documentation with playground +- Multi-language/versioned documentation +- Branding and customization + +Navigation and structure + +How navigation array maps to site structure +Difference between navigation, tabs, and anchors +External links vs internal pages + +Troubleshooting +* Schema validation errors and fixes +* File path conventions (relative vs absolute) +* Navigation nesting limitations + +Advanced features +* API playground configuration scenarios +* Multi-version documentation strategy +* Custom integrations and analytics +* SEO optimization settings ## Reference -This section contains the full reference for the docs.json file. +This section contains the full reference for the `docs.json` file. ### Customization From bbf27d16b774abf0fc6ecbd9d336d421df557c20 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 10 Jun 2025 15:43:45 -0700 Subject: [PATCH 02/17] add conceptual content --- settings.mdx | 75 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/settings.mdx b/settings.mdx index a094769ca..8d3a07fb4 100644 --- a/settings.mdx +++ b/settings.mdx @@ -4,43 +4,34 @@ description: "Configure the global settings for your documentation" icon: "settings-2" --- -Your `docs.json` file turns a collection of Markdown files into a navigable, customized documentation site. This configuration file is required for every documentation site and controls everything from styling and navigation to integrations. +The `docs.json` file turns a collection of Markdown files into a navigable, customized documentation site. This configuration file is required for every documentation site and controls everything from styling and navigation to integrations. Settings in `docs.json` apply to all pages globally. Changes to your `docs.json` take effect when your site builds. -## Configuring settings +## Configuring `docs.json` -TODO: +Your `docs.json` file controls how your documentation site looks, behaves, and is organized. You can configure everything from basic branding like colors and logos to advanced features like API playgrounds, versioning, and multi-language support. -Required vs optional settings +You only need to specify `theme`, `name`, `colors.primary`, and `navigation` to get started. Most fields are optional and you can add them as your documentation needs grow. -Minimal working configuration example - -Most impactful settings to begin with (name, colors, navigation) - -Configuration patterns -Possibly four tabbed examples: -- Basic documentation site setup -- API documentation with playground -- Multi-language/versioned documentation -- Branding and customization - -Navigation and structure +For the best editing experience, include the schema reference at the top of your docs.json file: -How navigation array maps to site structure -Difference between navigation, tabs, and anchors -External links vs internal pages - -Troubleshooting -* Schema validation errors and fixes -* File path conventions (relative vs absolute) -* Navigation nesting limitations +```json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Your Docs", + "colors": { + "primary": "#ff0000" + }, + "navigation": { + // your navigation structure + }, + // rest of your configuration +} +``` -Advanced features -* API playground configuration scenarios -* Multi-version documentation strategy -* Custom integrations and analytics -* SEO optimization settings +This enables autocomplete, validation, and helpful tooltips in most code editors. ## Reference @@ -286,6 +277,8 @@ This section contains the full reference for the `docs.json` file. The navigation structure of the content + TODO: * Navigation nesting limitations + Add external links that will appear on all sections and pages irregardless of navigation nesting @@ -814,12 +807,30 @@ This section contains the full reference for the `docs.json` file. ## Validation - -It is advised to include the following schema reference at the top of your docs.json file to ensure proper validation while editing: +TODO: * Schema validation errors and fixes +It is advised to include the following schema reference at the top of your `docs.json` file to ensure proper validation while editing: ```json { "$schema": "https://mintlify.com/docs.json", ... } -``` \ No newline at end of file +``` + +## Examples +Minimal working configuration example + +Configuration patterns +Possibly four tabbed examples: +- Basic documentation site setup +- API documentation with playground +- Multi-language/versioned documentation +- Branding and customization + +Advanced features +* API playground configuration scenarios +* Multi-version documentation strategy +* Custom integrations and analytics +* SEO optimization settings + +TODO: \ No newline at end of file From 16ad42677dea34bba34cc118deb76c2fca704299 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 10 Jun 2025 16:17:14 -0700 Subject: [PATCH 03/17] fill empty ResponseFields --- settings.mdx | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/settings.mdx b/settings.mdx index 8d3a07fb4..594559f7b 100644 --- a/settings.mdx +++ b/settings.mdx @@ -193,7 +193,7 @@ This section contains the full reference for the `docs.json` file. - The default light/dark mode. Defaults to `system` + The default light/dark mode. Defaults to `system`. Whether to hide the light / dark mode toggle. Defaults to `true`. @@ -209,8 +209,10 @@ This section contains the full reference for the `docs.json` file. + The path to the light background image. + The path to the dark background image. @@ -248,9 +250,10 @@ This section contains the full reference for the `docs.json` file. + The label for the link. This is the text that will be displayed in the navbar. - A valid path or external link + A valid path or external link. The icon to be displayed in the navbar. @@ -261,12 +264,13 @@ This section contains the full reference for the `docs.json` file. + The type of button to be displayed in the navbar. `button` will display a button with a label. `github` will display a GitHub icon and the repository name. The label for the primary button. This only applies when `type` is set to `button`. - A valid path or external link. If `type` is set to `github`, this will be the URL to the repository. + A valid path or external link. If `type` is set to `github`, this must be a URL for a GitHub repository. @@ -492,10 +496,13 @@ This section contains the full reference for the `docs.json` file. + The source path to be redirected. + The destination path to be redirected to. + Whether the redirect is permanent. Defaults to `true`. @@ -538,14 +545,16 @@ This section contains the full reference for the `docs.json` file. - A string or an array of strings of absolute or relative urls pointing to the AsyncAPI file(s) + A string or an array of strings of absolute or relative URLs pointing to the AsyncAPI file(s) + The path to the AsyncAPI files. Minimum length: 1 + The directory to search for AsyncAPI files. @@ -599,6 +608,7 @@ This section contains the full reference for the `docs.json` file. + The server configuration for the API. @@ -641,6 +651,7 @@ This section contains the full reference for the `docs.json` file. + The API key for Amplitude. @@ -648,6 +659,7 @@ This section contains the full reference for the `docs.json` file. + The public API key for Clearbit. @@ -655,6 +667,7 @@ This section contains the full reference for the `docs.json` file. + The site ID for Fathom. @@ -689,6 +702,7 @@ This section contains the full reference for the `docs.json` file. + The app ID for Heap. @@ -696,8 +710,10 @@ This section contains the full reference for the `docs.json` file. + The Hotjar ID. + The Hotjar script version. @@ -723,6 +739,7 @@ This section contains the full reference for the `docs.json` file. + The app ID for Logrocket. @@ -730,6 +747,7 @@ This section contains the full reference for the `docs.json` file. + The project token for Mixpanel. @@ -737,6 +755,7 @@ This section contains the full reference for the `docs.json` file. + The script source for Osano. @@ -744,6 +763,7 @@ This section contains the full reference for the `docs.json` file. + The ID for Pirsch. @@ -755,6 +775,7 @@ This section contains the full reference for the `docs.json` file. Must match pattern: ^phc\_ + The API host for Posthog. @@ -762,14 +783,17 @@ This section contains the full reference for the `docs.json` file. + The domain for Plausible. + The server for Plausible. + The key for Segment. @@ -777,6 +801,7 @@ This section contains the full reference for the `docs.json` file. + Whether to enable telemetry. Defaults to `true`. From 88b753610df25756697a52394ecf578d224949fd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 10 Jun 2025 16:30:42 -0700 Subject: [PATCH 04/17] remove redundant section --- settings.mdx | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/settings.mdx b/settings.mdx index 594559f7b..d39d8f9c5 100644 --- a/settings.mdx +++ b/settings.mdx @@ -801,15 +801,17 @@ This section contains the full reference for the `docs.json` file. - Whether to enable telemetry. Defaults to `true`. + Whether to enable telemetry. + The key for cookies. + The value for cookies. @@ -830,18 +832,6 @@ This section contains the full reference for the `docs.json` file. - -## Validation -TODO: * Schema validation errors and fixes -It is advised to include the following schema reference at the top of your `docs.json` file to ensure proper validation while editing: - -```json -{ - "$schema": "https://mintlify.com/docs.json", - ... -} -``` - ## Examples Minimal working configuration example From 5f80e2e2545fa1d9c863f782075a327b133202e3 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 15:04:10 -0700 Subject: [PATCH 05/17] update title, description, intro --- settings.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/settings.mdx b/settings.mdx index fc3395266..00c34caa3 100644 --- a/settings.mdx +++ b/settings.mdx @@ -1,13 +1,13 @@ --- -title: "Settings" -description: "Configure the global settings for your documentation" +title: "Global Settings" +description: "Configure site-wide settings with the `docs.json` file" icon: "settings-2" keywords: ["docs.json", "settings", "customization", "configuration"] --- -The `docs.json` file turns a collection of Markdown files into a navigable, customized documentation site. This configuration file is required for every documentation site and controls everything from styling and navigation to integrations. +The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. -Settings in `docs.json` apply to all pages globally. Changes to your `docs.json` take effect when your site builds. +Settings in `docs.json` apply globally to all pages. Changes to your `docs.json` take effect when your site builds. ## Configuring `docs.json` From 76bcec19d9341b6c96eff7a1b38f6afcaef0186b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 15:14:19 -0700 Subject: [PATCH 06/17] update setting up your `docs.json` --- settings.mdx | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/settings.mdx b/settings.mdx index 00c34caa3..d01f2b66c 100644 --- a/settings.mdx +++ b/settings.mdx @@ -9,13 +9,11 @@ The `docs.json` file lets you turn a collection of Markdown files into a navigab Settings in `docs.json` apply globally to all pages. Changes to your `docs.json` take effect when your site builds. -## Configuring `docs.json` +## Setting up your `docs.json` -Your `docs.json` file controls how your documentation site looks, behaves, and is organized. You can configure everything from basic branding like colors and logos to advanced features like API playgrounds, versioning, and multi-language support. +To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow. -You only need to specify `theme`, `name`, `colors.primary`, and `navigation` to get started. Most fields are optional and you can add them as your documentation needs grow. - -For the best editing experience, include the schema reference at the top of your docs.json file: +For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors: ```json { @@ -26,14 +24,12 @@ For the best editing experience, include the schema reference at the top of your "primary": "#ff0000" }, "navigation": { - // your navigation structure + // Your navigation structure }, - // rest of your configuration + // The rest of your configuration } ``` -This enables autocomplete, validation, and helpful tooltips in most code editors. - ## Reference This section contains the full reference for the `docs.json` file. From 387e4c487b29564f26c600f597169366e8c7c17c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 15:58:10 -0700 Subject: [PATCH 07/17] update customization reference --- settings.mdx | 110 ++++++++++++++++++++++++++++----------------------- 1 file changed, 60 insertions(+), 50 deletions(-) diff --git a/settings.mdx b/settings.mdx index d01f2b66c..13c2f5e1e 100644 --- a/settings.mdx +++ b/settings.mdx @@ -37,17 +37,19 @@ This section contains the full reference for the `docs.json` file. ### Customization - One of the following: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`. + The layout theme of your site. - The layout theme of the project. Check out the [Themes](themes) page for more information. + One of the following: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`. + + See [Themes](themes) for more information. - The name of the project, organization, or product + The name of your project, organization, or product. - The colors to use in your documentation. At the very least, you must define the primary color. For example: + The colors to use in your documentation. A primary color is required. For example: ```json { "colors": { @@ -58,126 +60,133 @@ This section contains the full reference for the `docs.json` file. - The primary color of the theme + The primary color of your theme. - Must be a hex code beginning with `#` + Must be a hex code beginning with `#`. - The light color of the theme. Used for dark mode + Primary color variant for light mode. - Must be a hex code beginning with `#` + Must be a hex code beginning with `#`. - The dark color of the theme. Used for light mode + Primary color variant for dark mode. - Must be a hex code beginning with `#` + Must be a hex code beginning with `#`. - Optional description used for SEO and LLM indexing + Description of your site for SEO and AI indexing. - The logo (for both light and dark mode) + Your 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 your logo file for light mode. Include 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` + Path pointing to your logo file for dark mode. Include 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 URL to redirect to when clicking the logo. If not provided, the logo will link to your homepage. Example: `https://mintlify.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 to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. + Can be a single file or separate files for light and dark mode. Example: `/favicon.png` - Path pointing to the light favicon file to use in dark mode, including the file extension. Example: `/favicon.png` + Path to your favicon file for light mode. Include 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` + Path to your favicon file for dark mode. Include the file extension. Example: `/favicon-dark.png` - Styling configurations + Visual styling configurations. - The eyebrows style of the content. Defaults to `section`. + The style of the page eyebrow. Choose `section` to show the section name or `breadcrumbs` to show the full navigation path. Defaults to `section`. - The codeblock theme. Defaults to `system`. + The theme of the code blocks. Choose `system` to match the site theme or `dark` for always dark code blocks. Defaults to `system`. - Icon library settings + Icon library settings. - The icon library to be used. Defaults to `fontawesome`. + Icon library to use throughout your documentation. Defaults to `fontawesome`. + + + You can specify a URL for any individual icon, regardless of the library setting. + + Font configuration for your documentation. - The font family, such as "Open Sans", "Playfair Display" + 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. + Font weight, such as 400 or 700. Variable fonts support precise weights such as 550. - The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 + URL to your font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2. - The font format, can be one of woff, woff2 + Font file format. + Override font settings specifically for headings. - The font family, such as "Open Sans", "Playfair Display" + 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. + Font weight, such as 400, 700. Variable fonts support precise weights such as 550. - The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 + URL to your font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2. - The font format, can be one of woff, woff2 + Font file format. + Override font settings specifically for body text. - The font family, such as "Open Sans", "Playfair Display" + 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. + Font weight, such as 400, 700. Variable fonts support precise weights such as 550. - The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 + URL to your font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2. - The font format, can be one of woff, woff2 + Font file format. @@ -186,49 +195,50 @@ This section contains the full reference for the `docs.json` file. - Light / dark mode toggle settings + Light/dark mode toggle settings. - The default light/dark mode. Defaults to `system`. + Default theme mode. Choose `system` to match users' OS settings, or `light` or `dark` to force a specific mode. Defaults to `system`. - Whether to hide the light / dark mode toggle. Defaults to `true`. + Whether to hide the light/dark mode toggle. Defaults to `true`. - Background color and decoration settings + Background color and decoration settings. + Background image for your site. Can be a single file or separate files for light and dark mode. - The path to the light background image. + Path to your background image for light mode. Include the file extension. Example: `/background.png`. - The path to the dark background image. + Path to your background image for dark mode. Include the file extension. Example: `/background-dark.png`. - The background decoration of the theme + Background decoration for your theme. - The colors of the background + Custom background colors for light and dark modes. - The color in hex format to use in light mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Background color for light mode. + + Must be a hex code beginning with `#`. - The color in hex format to use in dark mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Background color for dark mode. + + Must be a hex code beginning with `#`. From db856b0934f0d956700e0e80d1a4c139846c4abe Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:00:23 -0700 Subject: [PATCH 08/17] navbar & navigation reference --- settings.mdx | 96 ++++++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 45 deletions(-) diff --git a/settings.mdx b/settings.mdx index 13c2f5e1e..3f6112545 100644 --- a/settings.mdx +++ b/settings.mdx @@ -249,35 +249,36 @@ This section contains the full reference for the `docs.json` file. ### Structure - Navbar content and settings + Navigation bar items. - The links in the navbar + Links to display in the navbar - The label for the link. This is the text that will be displayed in the navbar. + Text for the link. - A valid path or external link. + URL or path for the link destination. - The icon displayed for a link. Can be a URL, Font Awesome icon, or Lucide icon. + Icon for the link. Can be a URL (relative or external), Font Awesome icon, or Lucide icon. + Primary button in the navbar. - The type of button to be displayed in the navbar. `button` will display a button with a label. `github` will display a GitHub icon and the repository name. + Button style. Choose `button` for a standard button with a label or `github` for a link to a GitHub repository with icon. - The label for the primary button. This only applies when `type` is set to `button`. + Button text. Only applies when `type` is `button`. - A valid path or external link. If `type` is set to `github`, this must be a URL for a GitHub repository. + Button destination. Must be a valid path or external URL. If `type` is `github`, must be a GitHub repository URL. @@ -286,152 +287,157 @@ This section contains the full reference for the `docs.json` file. - The navigation structure of the content - - TODO: * Navigation nesting limitations + The navigation structure of your content. - Add external links that will appear on all sections and pages irregardless of navigation nesting + Global navigation elements that appear accross all pages and sections. + Language switcher configuration for multi-language sites. - The name of the language in the ISO 639-1 format + Language code in ISO 639-1 format - Whether this language is the default language + Whether this is the default language. - Whether the current option is default hidden + Whether to hide this language option by default. - A valid path or external link + A valid path or external link to this language version of your documentation. + Version switcher configuration for multi-version sites. - The name of the version + Display name of the version. Minimum length: 1 - Whether this version is the default version + Whether this is the default version. - Whether the current option is default hidden + Whether to hide this version option by default. - An external link + URL or path to this version of your documentation. + Top-level navigation tabs for organizing major sections. - The name of the tab + Display name of the tab. Minimum length: 1 - The icon to be displayed in the section + Icon for the tab. Can be a URL (relative or external), Font Awesome icon, or Lucide icon. - Whether the current option is default hidden + Whether to hide this tab by default. - An external link + URL or path for the tab destination. + Anchored links that appear prominently in the sidebar navigation. - The name of the anchor + Display name of the anchor. Minimum length: 1 - The icon to be displayed in the section + Icon for the anchor. Can be a URL (relative or external), Font Awesome icon, or Lucide icon. + Custom colors for the anchor. - The color in hex format to use in light mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Anchor color for light mode. + + Must be a hex code beginning with `#`. - The color in hex format to use in dark mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Anchor color for dark mode. + + Must be a hex code beginning with `#`. - Whether the current option is default hidden + Whether to hide this anchor by default. - A valid path or external link + URL or path for the anchor destination. + Dropdown menus for organizing related content. + - The name of the dropdown + Display name of the dropdown. Minimum length: 1 - The icon to be displayed in the section + Icon for the dropdown. Can be a URL (relative or external), Font Awesome icon, or Lucide icon. - Whether the current option is default hidden + Whether to hide this dropdown by default. - An external link + URL or path for the dropdown destination. - Organizing by [languages](navigation#localization) + Language switcher for [multi-language](navigation#languages) sites. - Organizing by [versions](navigation#versions) + Version switcher for sites with multiple [versions](navigation#versions). - Organizing by [tabs](navigation#divisions#tabs) + Top-level navigation [tabs](navigation#tabs). - Organizing by [anchors](navigation#divisions#anchors) + Sidebar [anchors](navigation#anchors). - Organizing by [dropdowns](navigation#divisions#dropdowns) + [Dropdowns](navigation#dropdowns) for grouping related content. - Organizing by [groups](navigation#pages#pages) + [Groups](navigation#groups) for organizing content into sections. - An array of [page paths or groups](navigation#pages#groups) + Individual [pages](navigation#pages) that make up your documentation. From 08b9a3cc3cf4c56947aa4cb4db90917bfe7180bd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:09:55 -0700 Subject: [PATCH 09/17] footer & banner --- settings.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/settings.mdx b/settings.mdx index 3f6112545..1203d0c6e 100644 --- a/settings.mdx +++ b/settings.mdx @@ -445,11 +445,11 @@ This section contains the full reference for the `docs.json` file. - Footer configurations + Footer content and social media links. - 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: + Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example: ```json { "x": "https://x.com/mintlify" @@ -459,25 +459,25 @@ This section contains the full reference for the `docs.json` file. Valid property names: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast` - The links to be displayed in the footer + Links to display in the footer. - The header title of the column + Header title for the column. Minimum length: 1 - The links to be displayed in the column + Links to display in the column. - The label of the link + Link text. Minimum length: 1 - The url of the link + Link destination URL. @@ -488,11 +488,11 @@ This section contains the full reference for the `docs.json` file. - Banner configurations + Site-wide banner displayed at the top of pages. - The content of the banner. This can be a string of text or a markdown string. For example: + The content of the banner. Supports plain text and Markdown formatting. For example: ```json { "content": "🚀 Banner is live! [Learn more](mintlify.com)" @@ -500,7 +500,7 @@ This section contains the full reference for the `docs.json` file. ``` - Whether the banner is dismissible. Defaults to `false`. + Whether users can dismiss the banner. Defaults to `false`. From c2d5f75324886f8177111cec855c0b715986424e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:15:02 -0700 Subject: [PATCH 10/17] redirects & contextual menu --- settings.mdx | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/settings.mdx b/settings.mdx index 1203d0c6e..8a7578f93 100644 --- a/settings.mdx +++ b/settings.mdx @@ -506,34 +506,37 @@ This section contains the full reference for the `docs.json` file. + Redirects for moved, renamed, or deleted pages. - The source path to be redirected. + Source path to redirect from. Example: `/old-page` - The destination path to be redirected to. + Destination path to redirect to. Example: `/new-page` - Whether the redirect is permanent. Defaults to `true`. + Whether to use a permanent redirect (301). Defaults to `true`. + Contextual menu for AI-optimized content and integrations. + - The options to be displayed in the contextual menu. The first option is the default option. - - `copy`: Copy the current page as markdown to the clipboard - - `view`: View the current page as markdown in a new tab - - `chatgpt`: Feed the current page to ChatGPT - - `claude`: Feed the current page to Claude + Actions available in the contextual menu. The first option appears as the default. + - `copy`: Copy the current page as Markdown to the clipboard. + - `view`: View the current page as Markdown in a new tab. + - `chatgpt`: Send the current page content to ChatGPT. + - `claude`: Send the current page content to Claude. Contextual Menu - - The contextual menu is only available on preview & production deployments. - + + The contextual menu is only available on preview and production deployments. + From 0371c2a222b7555c4b333d6f274b575cea4d7d8b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:23:36 -0700 Subject: [PATCH 11/17] api ref --- settings.mdx | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/settings.mdx b/settings.mdx index 8a7578f93..7589e339a 100644 --- a/settings.mdx +++ b/settings.mdx @@ -544,47 +544,52 @@ This section contains the full reference for the `docs.json` file. ### API Configurations - API reference configuration and playground settings + API documentation and interactive playground settings. - A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s) + OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths. - + URL or path to your OpenAPI specification file. + Minimum length: 1 - no starting slash in the directory + Directory to search for OpenAPI files. + + Do not include a leading slash. - A string or an array of strings of absolute or relative URLs pointing to the AsyncAPI file(s) + AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths. - The path to the AsyncAPI files. + URL or path to your AsyncAPI specification file. Minimum length: 1 - The directory to search for AsyncAPI files. + Directory to search for AsyncAPI files. + + Do not include a leading slash. - Configurations for the API parameters + Display settings for API parameters. - The view mode of expandable API parameters. Defaults to `closed`. + Whether to expand all parameters by default. Defaults to `closed`. - Configurations for the API playground + API playground settings. @@ -596,35 +601,35 @@ This section contains the full reference for the `docs.json` file. - Configurations for the autogenerated API examples + Configurations for the autogenerated API examples. Example languages for the autogenerated API snippets - Whether to show optional parameters in api examples, defaults to `all` + Whether to show optional parameters in API examples. Defaults to `all`. - Configurations for API pages generated from MDX files + Configurations for API pages generated from `MDX` files. - Authentication configuration for the API + Authentication configuration for MDX-based API requests. - Authentication method for the API + Authentication method for API requests. - Authentication name for the API + Authentication name for API requests. - The server configuration for the API. + Server configuration for API requests. From 7ea9a925f989c9bfe11502703c7559a459f680be Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:29:04 -0700 Subject: [PATCH 12/17] SEO and search ref --- settings.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/settings.mdx b/settings.mdx index 7589e339a..ddff7d311 100644 --- a/settings.mdx +++ b/settings.mdx @@ -637,27 +637,27 @@ This section contains the full reference for the `docs.json` file. -### SEO & Search +### SEO and search - SEO indexing configurations + 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) + Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/settings/seo#common-meta-tags-reference) for options. - 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`. + Specify which pages search engines should index. Choose `navigable` to index only pages that are in your `docs.json` navigation or choose `all` to index every page. Defaults to `navigable`. - Search display settings + Search display settings. - The prompt to be displayed in the search bar placeholder + Placeholder text to display in the search bar. From 57146d7caa241efdc53d48679fb3a998f7e2b8e6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 16 Jun 2025 17:36:40 -0700 Subject: [PATCH 13/17] integrations & errors --- settings.mdx | 107 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 38 deletions(-) diff --git a/settings.mdx b/settings.mdx index ddff7d311..73060f792 100644 --- a/settings.mdx +++ b/settings.mdx @@ -665,161 +665,186 @@ This section contains the full reference for the `docs.json` file. ### Integrations - Configurations for official integrations + Third-party integrations. + Amplitude analytics integration. - The API key for Amplitude. + Your Amplitude API key. - + Clearbit data enrichment integration. + - The public API key for Clearbit. + Your Clearbit API key. - + Fathom analytics integration. + - The site ID for Fathom. + Your Fathom site ID. - + Front chat integration. + + Your Front chat snippet ID. Minimum length: 6 - + Google Analytics 4 integration. + - + Your Google Analytics 4 measurement ID. + Must match pattern: ^G - + Google Tag Manager integration. + - + Your Google Tag Manager tag ID. + Must match pattern: ^G - + Heap analytics integration. + - The app ID for Heap. + Your Heap app ID. - + Hotjar integration. + - The Hotjar ID. + Your Hotjar ID. - The Hotjar script version. + Your Hotjar script version. - + Intercom integration. + - + Your Intercom app ID. + Minimum length: 6 - + Koala integration. + - + Your Koala public API key. + Minimum length: 2 - + LogRocket integration. + - The app ID for Logrocket. + Your LogRocket app ID. + Mixpanel integration. - The project token for Mixpanel. + Your Mixpanel project token. - + Osano integration. + - The script source for Osano. + Your Osano script source. - + Pirsch analytics integration. + - The ID for Pirsch. + Your Pirsch ID. - + PostHog integration. + - + Your PostHog API key. + Must match pattern: ^phc\_ - The API host for Posthog. + Your PostHog API host. - + Plausible analytics integration. + - The domain for Plausible. + Your Plausible domain. - The server for Plausible. + Your Plausible server. + Segment integration. + - The key for Segment. + Your Segment key. - + Telemetry settings. + Whether to enable telemetry. @@ -827,12 +852,14 @@ This section contains the full reference for the `docs.json` file. + Cookie settings. + - The key for cookies. + Key for cookies. - The value for cookies. + Value for cookies. @@ -842,11 +869,15 @@ This section contains the full reference for the `docs.json` file. ### Errors + Error handling settings. + + 404 "Page not found" error handling. + - Whether to redirect to the home page, if the page is not found + Whether to automatically redirect to the home page when a page is not found. From 77ab6f72a0f3bb13f000de2baf2b1b6a3cf54b7d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 17 Jun 2025 09:51:22 -0700 Subject: [PATCH 14/17] add example configs --- settings.mdx | 506 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 492 insertions(+), 14 deletions(-) diff --git a/settings.mdx b/settings.mdx index 73060f792..591a2afcb 100644 --- a/settings.mdx +++ b/settings.mdx @@ -885,17 +885,495 @@ This section contains the full reference for the `docs.json` file. ## Examples -Minimal working configuration example - -Configuration patterns -Possibly four tabbed examples: -- Basic documentation site setup -- API documentation with playground -- Multi-language/versioned documentation -- Branding and customization - -Advanced features -* API playground configuration scenarios -* Multi-version documentation strategy -* Custom integrations and analytics -* SEO optimization settings + + + + ```json title="docs.json" wrap lines + { + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "Example Co.", + "description": "Example Co. is a company that provides example content and placeholder text.", + "colors": { + "primary": "#3B82F6", + "light": "#F8FAFC", + "dark": "#0F172A" + }, + "navigation": { + "dropdowns": [ + { + "dropdown": "Documentation", + "icon": "book", + "description": "How to use the Example Co. product", + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart" + ] + }, + { + "group": "Customization", + "pages": [ + "settings", + "users", + "features" + ] + }, + { + "group": "Billing", + "pages": [ + "billing/overview", + "billing/payments", + "billing/subscriptions" + ] + } + ] + }, + { + "dropdown": "Changelog", + "icon": "history", + "description": "Updates and changes", + "pages": [ + "changelog" + ] + } + ] + }, + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg", + "href": "https://example.com" + }, + "navbar": { + "links": [ + { + "label": "Community", + "href": "https://example.com/community" + } + ], + "primary": { + "type": "button", + "label": "Get Started", + "href": "https://example.com/start" + } + }, + "footer": { + "socials": { + "x": "https://x.com/example", + "linkedin": "https://www.linkedin.com/company/example", + "github": "https://github.com/example", + "slack": "https://example.com/community" + }, + "links": [ + { + "header": "Resources", + "items": [ + { + "label": "Customers", + "href": "https://example.com/customers" + }, + { + "label": "Enterprise", + "href": "https://example.com/enterprise" + }, + { + "label": "Request Preview", + "href": "https://example.com/preview" + } + ] + }, + { + "header": "Company", + "items": [ + { + "label": "Careers", + "href": "https://example.com/careers" + }, + { + "label": "Blog", + "href": "https://example.com/blog" + }, + { + "label": "Privacy Policy", + "href": "https://example.com/legal/privacy" + } + ] + } + ] + }, + "integrations": { + "ga4": { + "measurementId": "G-XXXXXXXXXX" + }, + "koala": { + "publicApiKey": "pk_example_key_123" + }, + "telemetry": { + "enabled": true + }, + "cookies": { + "key": "example_cookie_key", + "value": "example_cookie_value" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] + }, + "errors": { + "404": { + "redirect": true + } + } + } + ``` + + + ```json title="docs.json" wrap lines highlight={43-61, 72-79} + { + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "Example Co.", + "description": "Example Co. is a company that provides example content and placeholder text.", + "colors": { + "primary": "#3B82F6", + "light": "#F8FAFC", + "dark": "#0F172A" + }, + "navigation": { + "dropdowns": [ + { + "dropdown": "Documentation", + "icon": "book", + "description": "How to use the Example Co. product", + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart" + ] + }, + { + "group": "Customization", + "pages": [ + "settings", + "users", + "features" + ] + }, + { + "group": "Billing", + "pages": [ + "billing/overview", + "billing/payments", + "billing/subscriptions" + ] + } + ] + }, + { + "dropdown": "API reference", + "icon": "terminal", + "description": "How to use the Example Co. API", + "groups": [ + { + "group": "API reference", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "Endpoints", + "openapi": { + "source": "openapi.json" + } + } + ] + }, + { + "dropdown": "Changelog", + "icon": "history", + "description": "Updates and changes", + "pages": [ + "changelog" + ] + } + ] + }, + "api": { + "playground": { + "display": "interactive" + }, + "examples": { + "languages": ["javascript", "curl", "python"] + } + }, + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg", + "href": "https://example.com" + }, + "navbar": { + "links": [ + { + "label": "Community", + "href": "https://example.com/community" + } + ], + "primary": { + "type": "button", + "label": "Get Started", + "href": "https://example.com/start" + } + }, + "footer": { + "socials": { + "x": "https://x.com/example", + "linkedin": "https://www.linkedin.com/company/example", + "github": "https://github.com/example", + "slack": "https://example.com/community" + }, + "links": [ + { + "header": "Resources", + "items": [ + { + "label": "Customers", + "href": "https://example.com/customers" + }, + { + "label": "Enterprise", + "href": "https://example.com/enterprise" + }, + { + "label": "Request Preview", + "href": "https://example.com/preview" + } + ] + }, + { + "header": "Company", + "items": [ + { + "label": "Careers", + "href": "https://example.com/careers" + }, + { + "label": "Blog", + "href": "https://example.com/blog" + }, + { + "label": "Privacy Policy", + "href": "https://example.com/legal/privacy" + } + ] + } + ] + }, + "integrations": { + "ga4": { + "measurementId": "G-XXXXXXXXXX" + }, + "koala": { + "publicApiKey": "pk_example_key_123" + }, + "telemetry": { + "enabled": true + }, + "cookies": { + "key": "example_cookie_key", + "value": "example_cookie_value" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] + }, + "errors": { + "404": { + "redirect": true + } + } + } + ``` + + + ```json title="docs.json" wrap lines highlight={13-31} + { + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "Example Co.", + "description": "Example Co. is a company that provides example content and placeholder text.", + "colors": { + "primary": "#3B82F6", + "light": "#F8FAFC", + "dark": "#0F172A" + }, + "navigation": { + "global": { + "languages": [ + { + "language": "en", + "default": true, + "href": "/en" + }, + { + "language": "es", + "href": "/es" + }, + { + "language": "pt-BR", + "href": "/pt-BR" + }, + { + "language": "ko", + "href": "/ko" + } + ], + "dropdowns": [ + { + "dropdown": "Documentation", + "icon": "book", + "description": "How to use the Example Co. product", + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart" + ] + }, + { + "group": "Customization", + "pages": [ + "settings", + "users", + "features" + ] + }, + { + "group": "Billing", + "pages": [ + "billing/overview", + "billing/payments", + "billing/subscriptions" + ] + } + ] + }, + { + "dropdown": "Changelog", + "icon": "history", + "description": "Updates and changes", + "pages": [ + "changelog" + ] + } + ] + } + }, + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg", + "href": "https://example.com" + }, + "navbar": { + "links": [ + { + "label": "Community", + "href": "https://example.com/community" + } + ], + "primary": { + "type": "button", + "label": "Get Started", + "href": "https://example.com/start" + } + }, + "footer": { + "socials": { + "x": "https://x.com/example", + "linkedin": "https://www.linkedin.com/company/example", + "github": "https://github.com/example", + "slack": "https://example.com/community" + }, + "links": [ + { + "header": "Resources", + "items": [ + { + "label": "Customers", + "href": "https://example.com/customers" + }, + { + "label": "Enterprise", + "href": "https://example.com/enterprise" + }, + { + "label": "Request Preview", + "href": "https://example.com/preview" + } + ] + }, + { + "header": "Company", + "items": [ + { + "label": "Careers", + "href": "https://example.com/careers" + }, + { + "label": "Blog", + "href": "https://example.com/blog" + }, + { + "label": "Privacy Policy", + "href": "https://example.com/legal/privacy" + } + ] + } + ] + }, + "integrations": { + "ga4": { + "measurementId": "G-XXXXXXXXXX" + }, + "koala": { + "publicApiKey": "pk_example_key_123" + }, + "telemetry": { + "enabled": true + }, + "cookies": { + "key": "example_cookie_key", + "value": "example_cookie_value" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] + }, + "errors": { + "404": { + "redirect": true + } + } + } + ``` + + From 56587eb8a1391d954b0de0c50941f11ca6c31013 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 17 Jun 2025 09:59:07 -0700 Subject: [PATCH 15/17] include `docs.json` as next step in quickstart --- quickstart.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 536b48cc0..8a19a57ce 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -224,16 +224,19 @@ Enter your domain (for example, `docs.yourcompany.com`) and follow the provided Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation: - + + Configure site-wide styling, navigation, integrations, and more with the `docs.json` file. + + Learn how to customize colors, fonts, and the overall appearance of your documentation site. - + Structure your documentation with intuitive navigation to help users find what they need. - + Enhance your documentation with interactive components like accordions, tabs, and code samples. - + Create interactive API references with OpenAPI and AsyncAPI specifications. From c48e81bd5d06c20ebea336735df6650cb66ed78a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 17 Jun 2025 10:06:12 -0700 Subject: [PATCH 16/17] remove space --- quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickstart.mdx b/quickstart.mdx index 8a19a57ce..3dd52da63 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -224,7 +224,7 @@ Enter your domain (for example, `docs.yourcompany.com`) and follow the provided Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation: - + Configure site-wide styling, navigation, integrations, and more with the `docs.json` file. From 86e80b0be80660f097fde13f1aca682ddd2e7572 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 17 Jun 2025 16:10:50 -0700 Subject: [PATCH 17/17] add reviewer feedback --- settings.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/settings.mdx b/settings.mdx index 591a2afcb..bfa449fd0 100644 --- a/settings.mdx +++ b/settings.mdx @@ -7,7 +7,7 @@ keywords: ["docs.json", "settings", "customization", "configuration"] The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. -Settings in `docs.json` apply globally to all pages. Changes to your `docs.json` take effect when your site builds. +Settings in `docs.json` apply globally to all pages. ## Setting up your `docs.json` @@ -887,7 +887,7 @@ This section contains the full reference for the `docs.json` file. ## Examples - + ```json title="docs.json" wrap lines { "$schema": "https://mintlify.com/docs.json", @@ -1034,7 +1034,7 @@ This section contains the full reference for the `docs.json` file. } ``` - + ```json title="docs.json" wrap lines highlight={43-61, 72-79} { "$schema": "https://mintlify.com/docs.json", @@ -1208,7 +1208,7 @@ This section contains the full reference for the `docs.json` file. } ``` - + ```json title="docs.json" wrap lines highlight={13-31} { "$schema": "https://mintlify.com/docs.json",