diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 569a445d..e68e08c3 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,14 +1,14 @@ --- -title: 'Playground' -description: 'Enable users to interact with your API' -openapi: 'POST /project/update/{projectId}' +title: "Playground" +description: "Enable users to interact with your API" +openapi: "POST /project/update/{projectId}" hideApiMarker: true -icon: 'play' +icon: "play" --- -The API playground is an interactive environment to make requests and preview an API endpoint. +The API playground is an interactive environment to make requests and preview an API endpoint. Everything you see on this page will be auto-generated utilizing your OpenAPI spec. Autogenerating API pages with OpenAPI will automatically generate API playground. Read more about using OpenAPI [here](/api-playground/openapi). - + \ No newline at end of file diff --git a/content/components/sticky-examples.mdx b/content/components/sticky-examples.mdx index b44d3ba8..5adc14db 100644 --- a/content/components/sticky-examples.mdx +++ b/content/components/sticky-examples.mdx @@ -14,7 +14,12 @@ The `` component works similar to [CodeGroup](/content/component Please set a name on every code block you put inside RequestExample. + + This is where you can add additional custom languages as code examples for your API endpoints\! + + + ````md RequestExample Example @@ -25,6 +30,7 @@ Please set a name on every code block you put inside RequestExample. ```` + ## Response Example @@ -32,6 +38,7 @@ Please set a name on every code block you put inside RequestExample. The `` component is the same as `` but will show up underneath it. + ````md ResponseExample Example @@ -41,4 +48,5 @@ The `` component is the same as `` but will sho ```` - + + \ No newline at end of file diff --git a/settings/global.mdx b/settings/global.mdx index 9d8bd473..8794ad5e 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -30,6 +30,7 @@ Every documentation site requires a `docs.json` file that contains the core conf The colors to use in your documentation. At the very least, you must define the primary color. For example: + ```json { "colors": { @@ -41,18 +42,18 @@ Every documentation site requires a `docs.json` file that contains the core conf The primary color of the theme - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ The light color of the theme. Used for dark mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ The dark color of the theme. Used for light mode - - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ @@ -91,10 +92,10 @@ Every documentation site requires a `docs.json` file that contains the core conf Styling configurations - + The eyebrows style of the content. Defaults to `section`. - + The codeblock theme. Defaults to `system`. @@ -104,14 +105,13 @@ Every documentation site requires a `docs.json` file that contains the core conf Icon library settings - + The icon library to be used. Defaults to `fontawesome`. - The font family, such as "Open Sans", "Playfair Display" @@ -122,11 +122,10 @@ Every documentation site requires a `docs.json` file that contains the core conf The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 - + The font format, can be one of woff, woff2 - The font family, such as "Open Sans", "Playfair Display" @@ -137,13 +136,12 @@ Every documentation site requires a `docs.json` file that contains the core conf The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 - + The font format, can be one of woff, woff2 - The font family, such as "Open Sans", "Playfair Display" @@ -154,12 +152,11 @@ Every documentation site requires a `docs.json` file that contains the core conf The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2 - + The font format, can be one of woff, woff2 - @@ -167,7 +164,7 @@ Every documentation site requires a `docs.json` file that contains the core conf Light / dark mode toggle settings - + The default light/dark mode. Defaults to `system` @@ -181,15 +178,16 @@ Every documentation site requires a `docs.json` file that contains the core conf - + + - + The background decoration of the theme @@ -199,16 +197,15 @@ Every documentation site requires a `docs.json` file that contains the core conf The color in hex format to use in light mode - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ The color in hex format to use in dark mode - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ - @@ -223,6 +220,7 @@ Every documentation site requires a `docs.json` file that contains the core conf + A valid path or external link @@ -230,9 +228,9 @@ Every documentation site requires a `docs.json` file that contains the core conf - - + + The label for the primary button. This only applies when `type` is set to `button`. @@ -242,7 +240,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - @@ -255,9 +252,8 @@ Every documentation site requires a `docs.json` file that contains the core conf - - + The name of the language in the ISO 639-1 format @@ -272,7 +268,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - The name of the version @@ -291,7 +286,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - The name of the tab @@ -310,7 +304,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - The name of the anchor @@ -321,17 +314,16 @@ Every documentation site requires a `docs.json` file that contains the core conf The icon to be displayed in the section - The color in hex format to use in light mode - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ The color in hex format to use in dark mode - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Must match pattern: ^#([a-fA-F0-9]6|[a-fA-F0-9]3)$ @@ -343,7 +335,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - @@ -366,34 +357,25 @@ Every documentation site requires a `docs.json` file that contains the core conf Organizing by [languages](/navigation/localization) - Organizing by [versions](/navigation/versions) - Organizing by [tabs](/navigation/divisions#tabs) - Organizing by [anchors](/navigation/divisions#anchors) - - Organizing by [dropdowns](/navigation/divisions#dropdowns) - Organizing by [groups](/navigation/pages#pages) - An array of [page paths or groups](/navigation/pages#groups) - - @@ -403,12 +385,13 @@ Every documentation site requires a `docs.json` file that contains the core conf 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`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast` @@ -436,7 +419,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - @@ -446,6 +428,7 @@ Every documentation site requires a `docs.json` file that contains the core conf The content of the banner. This can be a string of text or a markdown string. For example: + ```json { "content": "šŸš€ Banner is live! [Learn more](mintlify.com)" @@ -459,27 +442,34 @@ Every documentation site requires a `docs.json` file that contains the core conf - + + + - + 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 - Contextual Menu + Contextual Menu The contextual menu is only available on preview & production deployments. @@ -499,7 +489,6 @@ Every documentation site requires a `docs.json` file that contains the core conf - Minimum length: 1 @@ -507,15 +496,15 @@ Every documentation site requires a `docs.json` file that contains the core conf - + A string or an array of strings of absolute or relative urls pointing to the AsyncAPI file(s) - Minimum length: 1 + @@ -523,7 +512,7 @@ Every documentation site requires a `docs.json` file that contains the core conf Configurations for the API playground - + The display mode of the API playground. Defaults to `interactive`. @@ -536,7 +525,11 @@ Every documentation site requires a `docs.json` file that contains the core conf - Example languages for the autogenerated API snippets + Specifies the default order of auto-generated API snippet languages. + + ``` + ["bash", "python", "javascript", "php", "go", "java"] + ``` @@ -548,7 +541,7 @@ Every documentation site requires a `docs.json` file that contains the core conf Authentication configuration for the API - + Authentication method for the API @@ -557,10 +550,10 @@ Every documentation site requires a `docs.json` file that contains the core conf + - @@ -573,7 +566,7 @@ Every documentation site requires a `docs.json` file that contains the core conf Meta tags added to every page. Must be a valid key-value pair. Possible options [here](https://mintlify.com/docs/settings/seo#supported-meta-tags) - + Specify which pages to be indexed by search engines. Setting `navigable` indexes pages that are set in navigation, `all` indexes all pages. Defaults to `navigable`. @@ -596,153 +589,147 @@ Every documentation site requires a `docs.json` file that contains the core conf - + - + - + - - Minimum length: 6 - - Must match pattern: ^G - - Must match pattern: ^G - + - + + - - Minimum length: 6 - - Minimum length: 2 - + - + - + - + - - Must match pattern: ^phc\_ + - + + + - + + + @@ -792,16 +779,15 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu settings. Learn more about the [properties](#properties) or from an [example](#example-mint-json) -## Properties + ## Properties -### Styling + ### Styling -{" "} - - - Name of your company or project. Used for the global title. - + {" "} + + 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 @@ -811,25 +797,19 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu 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` - - + + Path to the favicon image. For example: `/path/to/favicon.svg` + Hex color codes for your global theme @@ -838,16 +818,13 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu 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 @@ -855,37 +832,27 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu 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) + + {" "} -{" "} - - - 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. - - + + The global layout style of the documentation. + Set a decorative background. @@ -894,36 +861,30 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu The style of the decorative background. - + {" "} -{" "} - - - Set a custom background image to be displayed behind every page. - - - + + Set a custom background image to be displayed behind every page. + + Custom fonts. Apply globally or set different fonts for headings and the body text. -Example: + Example: -```json -"font": { - "headings": { - "family": "Roboto" - }, - "body": { - "family": "Oswald" - } -} -``` + ```json + "font": { + "headings": { + "family": "Roboto" + }, + "body": { + "family": "Oswald" + } + } + ``` @@ -931,26 +892,20 @@ Example: 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. @@ -959,31 +914,30 @@ Example: 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 - } - ``` + ```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. @@ -992,9 +946,7 @@ Example: The styling of the navigation item. - - Styling configurations for the topbar. @@ -1003,9 +955,7 @@ Example: The styling of the navigation item. - - The location options for the search bar. @@ -1014,15 +964,12 @@ Example: The location of the search bar. - + {" "} -{" "} - - - The style of the rounded edges. - - + + The style of the rounded edges. + The style of the code block. @@ -1032,10 +979,8 @@ Example: user's system preferences. - - -### Structure + ### Structure An array of groups with all the pages within that group @@ -1044,23 +989,17 @@ Example: The name of the group. - The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array. - The [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon for the group. Note: this only applies to sub-folders. - The type of icon (only for [Font Awesome](https://fontawesome.com/icons) icons). Must be one of: brands, duotone, light, sharp-solid, solid, thin - - - Array of names and urls of links you want to include in the topbar @@ -1068,82 +1007,72 @@ Example: 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. - -{" "} + Versions can be leveraged for localization. You can store translated content + under a version, and once you specify the `locale` any fixed text in Mintlify, + such as 'Was this page helpful?', will automatically be translated based on the + locale. We currently support localization in English, Chinese, Spanish, French, + Japanese, and Portuguese. - - Localization auto-translates the UI and fixed assets in the docs, such as "Was - this page helpful?". You must translate the content of the pages yourself. - + {" "} -For more information, please refer to our -[versioning & localization documentation](/navigation/versions). + + Localization auto-translates the UI and fixed assets in the docs, such as "Was + this page helpful?". You must translate the content of the pages yourself. + + For more information, please refer to our + [versioning & localization documentation](/navigation/versions). -Example: + Example: - ```json Default - "versions": ["v1.0", "v1.1"] - ``` - ```json Localization - "versions": [ - { - "name": "English", - "locale": "en", - }, - { - "name": "EspaƱol", - "locale": "es" - } - ] - ``` + ```json Default + "versions": ["v1.0", "v1.1"] + ``` + + + ```json Localization + "versions": [ + { + "name": "English", + "locale": "en", + }, + { + "name": "EspaƱol", + "locale": "es" + } + ] + ``` @@ -1151,39 +1080,34 @@ Example: The version name. - The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`. - Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version. - - - An array of the anchors, includes the icon, color, and url. -{" "} + {" "} -{" "} + {" "} - + -{" "} + {" "} -{" "} + {" "} - + @@ -1191,119 +1115,100 @@ Example: Example: `Community` - The [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon used to feature the anchor. Example: `comments` - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - Used if you want to hide an anchor until the correct docs version is selected. - - + Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - + One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - Override the default configurations for the top-most anchor. Note: if you have tabs configured, this does not apply. - + The name of the top-most anchor - - + Font Awesome icon. - - + One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - An array of navigational tabs. -Example: + Example: -```json -"tabs": [ - { - "name": "Writing Content", - "url": "content" - }, - { - "name": "API References", - "url": "api-playground" - } -] -``` + ```json + "tabs": [ + { + "name": "Writing Content", + "url": "content" + }, + { + "name": "API References", + "url": "api-playground" + } + ] + ``` The name of the tab label. - The start of the URL that marks what pages go in the tab. Generally, this is the name of the folder you put your pages in. - - + Pass `true` if you want to hide the tab until you directly link someone to docs inside it. - - - An object to configure the footer with socials and links. Example: -```json -"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", + ```json + "footer": { + "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" }, "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } + { + "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" } + ] + } ] } - ] -} -``` + ``` @@ -1311,52 +1216,40 @@ Example: Example: `x` - The URL to the social platform. Example: `https://x.com/mintlify` - - Title of the column - The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab. - - - Configurations to enable feedback buttons - + Enables a rating system for users to indicate whether the page has been helpful + + Enables a button to allow users to suggest edits via pull requests for public repositories. - - Enables a button to allow users to suggest edits via pull requests for public repositories. - - - If your docs repo is private, `suggestEdit` will not work. - + + If your docs repo is private, `suggestEdit` will not work. + - - + Enables a button to allow users to raise an issue about the documentation - - - Configurations to change the search prompt @@ -1365,10 +1258,8 @@ Example: Set the prompt for the search bar. Default is `Search...` - - -### API Configurations + ### API Configurations Configuration for API settings. Learn more about API pages at [API Components](/api-playground). @@ -1378,19 +1269,16 @@ Example: The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url options that the user can toggle. - - + The authentication strategy used for all API endpoints. - The name of the authentication parameter used in the API playground. If method is `basic`, the format should be `[usernameName]:[passwordName]` - The default value that's designed to be a prefix for the authentication input field. @@ -1398,25 +1286,22 @@ Example: - Configurations for the API playground - + Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` Learn more at the [playground guides](/api-playground) - - + By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior. Required for select request types, such as file uploads. - Configurations for API requests @@ -1432,12 +1317,11 @@ Example: - Configurations for the param fields in the API Playground - + The default expanded state of expandable options in the API playground. `"all"` - every expandable component is expanded @@ -1450,35 +1334,33 @@ Example: - - - A string or an array of strings of URL(s) or relative path(s) pointing to your OpenAPI file. -Examples: + Examples: - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - ```json Relative - "openapi": "/openapi.json" - ``` + ```json Absolute + "openapi": "https://example.com/openapi.json" + ``` - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` + + ```json Relative + "openapi": "/openapi.json" + ``` - + + ```json Multiple + "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] + ``` + - -### Integrations + ### Integrations Configurations to add third-party integrations (excluding analytics integrations) @@ -1487,35 +1369,30 @@ Examples: Enables Intercom widget on docs site. The value should be your Intercom App ID. - Enables Frontchat widget on docs site. The value should be your Frontchat App ID. - - - - - Configurations to add third-party analytics integrations. See full list of - supported analytics [here](/integrations/analytics/overview). - - -### Redirects + + Configurations to add third-party analytics integrations. See full list of + supported analytics [here](/integrations/analytics/overview). + + ### Redirects An array of paths you want to configure to permanently redirect to another path -Example: + Example: -```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" - } -] -``` + ```json + "redirects": [ + { + "source": "/source/path", + "destination": "/destination/path" + } + ] + ``` @@ -1523,41 +1400,35 @@ Example: Example: `/source` - The path that you want to redirect to. Example: `/destination` - - - -### Search Engine Optimization + ### Search Engine Optimization Settings for Search Engine Optimization. -Example: + Example: -```json -"seo": { - "indexHiddenPages": true -} -``` + ```json + "seo": { + "indexHiddenPages": true + } + ``` Enables indexing pages not included in `navigation`. - + ## Example `mint.json` -## Example `mint.json` - -Click on the following dropdown to view a sample configuration file + Click on the following dropdown to view a sample configuration file ```json @@ -1627,4 +1498,4 @@ Click on the following dropdown to view a sample configuration file } ``` - + \ No newline at end of file