diff --git a/advanced/custom/css.mdx b/advanced/custom/css.mdx index 18ffcc5..f0eeb93 100644 --- a/advanced/custom/css.mdx +++ b/advanced/custom/css.mdx @@ -7,11 +7,11 @@ description: 'Fully customize your documentation with custom CSS' Custom CSS is available as an add-on to the [pro plan](https://mintlify.com/pricing). -Add any number of CSS files to your repository and the defined class names will be applied and available across all of your MDX files. +Add CSS files to your repository to apply custom styling across your MDX files. -## Adding style.css +## Example Usage -For example, you can add the following `style.css` file to customize the styling of the navbar and footer. +Add a `style.css` file to customize UI elements: ```css #navbar { @@ -24,18 +24,19 @@ footer { } ``` -## Using Identifiers +## Common Identifiers -Mintlify has a set of common identifiers to help you tag important elements of the UI. Some, but not all are listed in the following: - -`#topbar-cta-button` `#navbar` `#sidebar` `#content-area` `#table-of-contents` +Key UI elements you can style: +- `#topbar-cta-button` +- `#navbar` +- `#sidebar` +- `#content-area` +- `#table-of-contents` - Use inspect element to find references to elements you're looking to - customize. + Use inspect element to find additional element references. - References and the styling of common elements are subject to change as the - platform evolves. Please use custom styling with caution. - + UI elements and styling may change as the platform evolves. Use custom styling with caution. + \ No newline at end of file diff --git a/advanced/custom/js.mdx b/advanced/custom/js.mdx index 6e71c9b..b845041 100644 --- a/advanced/custom/js.mdx +++ b/advanced/custom/js.mdx @@ -7,11 +7,11 @@ description: 'Add JavaScript functionality globally' Custom JS is available as an add-on to the [pro plan](https://mintlify.com/pricing). -Custom JS allows you to add custom executable code globally. It is the equivalent of adding a ` ``` -To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react` [package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application: +### React Integration ```jsx ``` -## Usage - -In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props: - -| Prop | Type | Description | -| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- | -| `connection` | [MintlifyWidgetConnectionProps](#mintlifywidgetconnectionProps) | Information needed to connect to our API. Required. | -| `display?` | [MintlifyWidgetDisplayProps](#mintlifywidgetdisplayProps) | Configurations for the widget appearance and interactions. | -| `tracking?` | [MintlifyWidgetTrackingFunctions](#mintlifywidgettrackingfunctions) | Callback functions for tracking analytics. | - -### MintlifyWidgetConnectionProps - -| Prop | Type | Description | -| -------- | -------- | ----------------------------------------------------------- | -| `apiKey` | `string` | Widget API key generated from Mintlify dashboard. Required. | -| `url?` | `string` | Used for internal testing only | - -### MintlifyWidgetDisplayProps - -| Prop | Type | Description | -| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- | -| `trigger?` | [MintlifyWidgetDisplayTriggerProps](#mintlifywidgetdisplaytriggerprops) | Appearance of the trigger. | -| `colors?` | [MintlifyWidgetDisplayColorsProps](#mintlifywidgetdisplaycolorsprops) | Colors used across the widget. | -| `chat?` | [MintlifyWidgetDisplayChatProps](#mintlifywidgetdisplaychatprops) | Configs specific to AI chat. | -| `isDarkMode?` | `boolean` | Controlled dark mode appearance. Defaults to OS preference. | - -#### MintlifyWidgetDisplayTriggerProps - -| Prop | Type | Description | -| ------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `type?` | `'button'`\|`'input'` | Type of the trigger to display. Defaults to `button`. | -| `label?` | `string` | Label displayed in the trigger. Defaults to `Get help` for the button trigger and `Ask anything...` for the input trigger. | -| `buttonIcon?` | `'chat'`\|`'sparkles'`\|`'mintlify'` | Icon used in the trigger. Only available for the `button` trigger. Defaults to `chat`. | -| `iconOnly?` | `boolean` | Only show icon in the trigger or not. Defaults to `false`. | - -Here is an overview of what the trigger looks like with different configurations. - -| `type='input'` | | -| -------------- | ------------------------------------------------------------ | -| | | - -| `type='button'` | `'chat'` | `'sparkles'` | `'mintlify'` | -| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `iconOnly=false` | | | | -| `iconOnly=true` | | | | - -#### MintlifyWidgetDisplayColorsProps +## Configuration -| Prop | Type | Description | -| --------------- | -------- | -------------------------------------------------------- | -| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. | -| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. | +The widget accepts the following main configuration props: -#### MintlifyWidgetDisplayChatProps +| Prop | Description | +| ------------ | ---------------------------------------------------------- | +| `connection` | Required. API connection settings (`apiKey` required) | +| `display` | Optional. Widget appearance and interaction settings | +| `tracking` | Optional. Analytics callback functions | -| Prop | Type | Description | -| ------------------------ | ---------- | ------------------------------------------------------------------ | -| `openCitationInSameTab?` | `boolean` | Open the citation url in the same tab or not. Defaults to `false`. | -| `exampleQueries?` | `string[]` | Example queries to prompt the user to ask. Defaults to `[]`. | +### Display Options -### MintlifyWidgetTrackingFunctions +- **Trigger Types**: Choose between `button` or `input` types +- **Colors**: Customize `primary` and `primaryLight` colors +- **Chat Settings**: Configure example queries and citation behavior +- **Appearance**: Control dark mode and trigger appearance -| Prop | Type | Description | -| --------------------- | ------------------------------------------ | -------------------------------------------------- | -| `trackChatEnter` | `()=> void` | Triggered when the user opens the chat widget. | -| `trackCitationClick` | `(title: string, url: string)=> void` | Triggered when the user clicks on a citation. | -| `trackChatThumbsUp` | `(query: string, response: string)=> void` | Triggered when the user thumbs up on a response. | -| `trackChatThumbsDown` | `(query: string, response: string)=> void` | Triggered when the user thumbs down on a response. | -| `trackChatFollowup` | `(query: string)=> void` | Triggered when the user asks a question. | -| `trackChatClose` | `(queriesCount: number)=> void` | Triggered when the user exits the chat widget. | +For detailed configuration options and tracking callbacks, visit our [GitHub repository](https://www.npmjs.com/package/@mintlify/widget-react). \ No newline at end of file diff --git a/api-playground/mdx/authentication.mdx b/api-playground/mdx/authentication.mdx index b6469ec..4e51da1 100644 --- a/api-playground/mdx/authentication.mdx +++ b/api-playground/mdx/authentication.mdx @@ -3,17 +3,13 @@ title: "Authentication" description: "You can set authentication parameters to let users use their real API keys." --- -## Enabling Authentication +## Authentication Methods -You can add an authentication method to your mint.json to enable it on every page or you can set it on a per-page basis. - -The page's authentication method will override mint.json if both are set. - -### Bearer Token +You can configure authentication either globally in `mint.json` or per-page in the page metadata. Page-level settings override global settings. -```json mint.json +```json Bearer Token "api": { "auth": { "method": "bearer" @@ -21,20 +17,7 @@ The page's authentication method will override mint.json if both are set. } ``` -```md Page Metadata ---- -title: "Your page title" -authMethod: "bearer" ---- -``` - - - -### Basic Authentication - - - -```json mint.json +```json Basic Auth "api": { "auth": { "method": "basic" @@ -42,20 +25,7 @@ authMethod: "bearer" } ``` -```md Page Metadata ---- -title: "Your page title" -authMethod: "basic" ---- -``` - - - -### API Key - - - -```json mint.json +```json API Key "api": { "auth": { "method": "key", @@ -64,24 +34,12 @@ authMethod: "basic" } ``` -```md Page Metadata +```md Disable Authentication --- -title: "Your page title" -authMethod: "key" +authMethod: "none" --- ``` -### None - -The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json. - - -```md Page Metadata ---- -title: "Your page title" -authMethod: "none" ---- -``` - +To set authentication for a specific page, add `authMethod: "[method]"` to the page's front matter. \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df..297f4cd 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -3,25 +3,24 @@ title: 'MDX Setup' description: 'Generate docs pages for your API endpoints using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Mintlify generates an API playground with request and response examples from your endpoint definitions. Here's how to set it up: - In your `mint.json` file, define your base URL and auth method: + In `mint.json`, set your base URL and auth method: ```json { "api": { - "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs + "baseUrl": "https://mintlify.com/api", "auth": { - "method": "bearer" // options: bearer, basic, key. + "method": "bearer" } } } ``` - If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field: - + To hide the playground, use: ```json { "api": { @@ -32,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js } ``` - Find a full list of API configurations [here](/settings/global#api-configurations). + See all API configurations [here](/settings/global#api-configurations). - - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + + For each endpoint, create an MDX file with: ```md --- @@ -46,20 +44,14 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js --- ``` - You can specify path parameters by adding the parameter name to the path, wrapped with `{}`: - - ```bash - https://api.example.com/v1/endpoint/{userId} - ``` + For path parameters, use `{paramName}` syntax: `https://api.example.com/v1/endpoint/{userId}` - - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. - + With configured `baseUrl`, you can use relative paths like `/v1/endpoint`. - - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation). + + Add your endpoint pages to the `navigation` field in `mint.json`. [Learn more](/settings/navigation). - + \ No newline at end of file diff --git a/api-playground/openapi/advanced-features.mdx b/api-playground/openapi/advanced-features.mdx index a262422..2f20d17 100644 --- a/api-playground/openapi/advanced-features.mdx +++ b/api-playground/openapi/advanced-features.mdx @@ -3,23 +3,23 @@ title: "Advanced Features" description: "Support for advanced OpenAPI features" --- -OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them with Mintlify. +OpenAPI 3 offers advanced features for complex APIs. Here's how to use them with Mintlify. ## `oneOf`, `anyOf`, `allOf` -For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the [Swagger documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially: +OpenAPI provides keywords to combine schemas: -- `oneOf` functions like an "exclusive-or" operator -- `anyOf` functions like an "or" operator -- `allOf` functions like an "and" operator +- `oneOf` - exclusive-or operator +- `anyOf` - or operator +- `allOf` - and operator -Mintlify treats the `oneOf` and `anyOf` keywords the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user. +Mintlify treats `oneOf` and `anyOf` the same way. -Mintlify currently does not support the `not` keyword. +The `not` keyword is not currently supported. -### Combining schemas with `allOf` +### Using `allOf` -Mintlify performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging [OpenAPI's reusable `components`](https://swagger.io/docs/specification/components/). +Mintlify combines properties of object schemas using `allOf`. Example: ```yaml org_with_users: @@ -29,32 +29,12 @@ org_with_users: properties: users: type: array - description: An array containing all users in the organization -... -components: - schemas: - Org: - type: object - properties: - id: - type: string - description: The ID of the organization + description: Array of organization users ``` - - - - The ID of the organization - - - An array containing all users in the organization - - - +### Using `oneOf` and `anyOf` -### Providing options with `oneOf` and `anyOf` - -When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. For example, here's how you might display two different types of delivery addresses: +Options are displayed in tabs. Use `title` field for clear labels: ```yaml delivery_address: @@ -64,74 +44,40 @@ delivery_address: properties: address_line_1: type: string - description: The street address of the recipient - ... - title: POBox type: object properties: box_number: type: string - description: The number of the PO Box - ... ``` - -
- - - - The street address of the residence - - - - - The number of the PO Box - - - -
- - ## `x-codeSamples` -If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within any request method, and has the following schema: +Add SDK examples to your API documentation using `x-codeSamples`. Required fields: - The language of the code sample. + Code language - The label for the sample. This is useful when providing multiple examples for a single endpoint. + Sample label - The source code of the sample. + Sample code -Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. - +Example: ```yaml paths: /plants: get: - ... x-codeSamples: - lang: bash - label: List all unwatered plants source: | planter list -u - lang: javascript - label: List all unwatered plants source: | const planter = require('planter'); planter.list({ unwatered: true }); - - lang: bash - label: List all potted plants - source: | - planter list -p - - lang: javascript - label: List all potted plants - source: | - const planter = require('planter'); - planter.list({ potted: true }); -``` +``` \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 7d45da4..c465a59 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -5,145 +5,53 @@ description: "Reference OpenAPI endpoints in your docs pages" ## Add an OpenAPI specification file -To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI -document in either JSON or YAML format that follows the -[OpenAPI specification](https://swagger.io/specification/). Your document must -follow OpenAPI specification 3.0+. +Ensure you have a valid OpenAPI 3.0+ document in either JSON or YAML format following the [OpenAPI specification](https://swagger.io/specification/). ## Auto-populate API pages -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor. +Add an `openapi` field to a tab or anchor in the `mint.json` to automatically generate API pages. The field can contain either: +- A path to an OpenAPI document in your docs repo +- A URL of a hosted OpenAPI document -**Example with Anchors:** - -```json {5} +```json { "anchors": [ { "name": "API Reference", "openapi": "/path/to/openapi.json", - "url": "api-reference", - "icon": "square-terminal" - } - ] -} -``` - -![](/images/anchors-autogeneration-anchors.png) - -**Example with Tabs:** - -```json {6} -{ - "tabs": [ - { - "name": "API Reference", - "url": "api-reference", - "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" + "url": "api-reference" } ] } ``` -![](/images/autogeneration-with-tabs.png) - -When using this option, the metadata for the generated pages will have the following default values: - -* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. - -* `description`: The `description` field from the OpenAPI operation, if present. - -* `version`: The `version` value from the anchor or tab, if present. - -There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page. - -## Create MDX files for API pages - -If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). - -![](/images/elevenlabs-mdx-autogeneration-example.png) - -### Autogenerate files +## Custom API pages -For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper. +### Auto-generate MDX files -Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) -autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the -OpenAPI document in your codebase. - -```bash -npx @mintlify/scraping@latest openapi-file -``` - -Add the `-o` flag to specify a folder to populate the files into. If a folder is -not specified, the files will populate in the working directory. +For large OpenAPI documents, use our scraper to generate MDX files: ```bash npx @mintlify/scraping@latest openapi-file -o api-reference ``` -Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). - -The scraper will output an array of -[Navigation entries](/settings/global#structure) containing your OpenAPI MDX -files. You can either append these entries to your existing Navigation, or -reorder and add the files to your navigation manually. - - - If your OpenAPI document is invalid, the files will not autogenerate. - - -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. +### Manual MDX creation -If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have -only one OpenAPI file - it will automatically detect your OpenAPI file. +Create custom MDX pages for API operations using the `openapi` field in the frontmatter: - - ```md Example - --- - title: "Get users" - openapi: "/path/to/openapi-1.json GET /users" - --- - ``` - - ```md Format - --- - title: "title of the page" - openapi: openapi-file-path method path - --- - ``` - - -
- - - The method and path must match the method and path specified in the OpenAPI - document exactly. If the endpoint doesn't exist in the OpenAPI file, - the page will be empty. - - -## Create MDX files for OpenAPI schemas +```md +--- +title: "Get users" +openapi: "/path/to/openapi.json GET /users" +--- +``` -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: +### OpenAPI Schemas - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` +Create pages for OpenAPI schemas using: - ```md Format - --- - openapi-schema: "schema-key" - --- - ``` - \ No newline at end of file +```md +--- +openapi-schema: "schema-key" +--- +``` \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 57cd936..a9fc1e5 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -5,28 +5,28 @@ description: "Use OpenAPI features to enhance your Mintlify docs" ## Describing your API -There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites: -- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) for familiarizing yourself with the OpenAPI syntax -- [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for all the details about the newest OpenAPI specification -- [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) for debugging your OpenAPI document -- [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action +Here are essential resources for working with OpenAPI: +- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) - Learn OpenAPI syntax +- [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) - Official specification +- [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) - Debug your OpenAPI document +- [Swagger's Editor](https://editor.swagger.io/) - See examples in action - Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). + While Swagger's Guide covers OpenAPI v3.0, it's mostly applicable to v3.1. See differences in [OpenAPI's blog](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). -## Specifying the URL for your API +## API Configuration -In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). +### Base URL +- Use the `servers` field to specify your API's base URL +- Required for Mintlify's API Playground functionality +- Multiple servers create a dropdown in the playground +- Can be overridden per path or operation -The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request. +### Authentication +- Define auth methods using `securitySchemes` +- Supports Basic, Bearer, and API Key authentication +- Apply auth using the `security` field +- Can be configured globally or per operation -If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation. - -## Specifying authentication - -Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. - -The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. - -If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. +For detailed guidance, refer to [Swagger's documentation](https://swagger.io/docs/specification/authentication/). \ No newline at end of file diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 85504e7..1656859 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -4,81 +4,34 @@ description: "Common issues with API References" icon: "triangle-exclamation" --- -API pages are complicated. As a result, there are a lot of things that can go wrong. -Here's a list of common issues we've seen customers run into: +Here are common issues and solutions for API References: - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, - or your OpenAPI document is invalid. - - Running `mintlify dev` locally should reveal some of these issues. - - To verify your OpenAPI document will pass validation: - - 1. Visit [this validator](https://apitools.dev/swagger-parser/online/) - 2. Switch to the "Validate text" tab - 3. Paste in your OpenAPI document - 4. Click "Validate it!" - - If the text box that appears below has a green border, your document has passed validation. - This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document - passes validation here, there's a great chance the problem is elsewhere. - - Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, - you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3): - - - - + Likely causes: Mintlify can't find your OpenAPI document or it's invalid. + To verify: + 1. Run `mintlify dev` locally + 2. Validate your OpenAPI document at [apitools.dev/swagger-parser/online](https://apitools.dev/swagger-parser/online/) + 3. Ensure you're not using OpenAPI 2.0 (use [editor.swagger.io](https://editor.swagger.io/) to convert to OpenAPI 3) - This is usually caused by a misspelled `openapi` field in the page metadata. Make sure - the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. - - Here's an example of how things might go wrong: - -```md get-user.mdx ---- -openapi: "GET /users/{id}/" ---- -``` - -```yaml openapi.yaml -paths: - "/users/{id}": - get: ... -``` - - Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI - document does not. + Common causes: + - Mismatched paths in metadata and OpenAPI document (check for exact matches, including slashes) + - Incorrect OpenAPI document filename reference - Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document - in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI - documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: - -```md api-reference/v1/users/get-user.mdx + Example: +```md --- -openapi: "v1 GET /users/{id}" +openapi: "GET /users/{id}/" # Path must exactly match OpenAPI document --- ``` - - If you have a custom domain configured, this could be an issue with your reverse proxy. By - default, requests made via the API Playground start with a `POST` request to the - `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` - requests, then all of these requests will fail. To fix this, configure your reverse proxy to - allow `POST` requests to the `/api/request` path. - - Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure - Mintlify to send requests directly to your backend with the `api.playground.disableProxy` - setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will - likely require you to configure CORS on your server, as these requests will now come directly - from your users' browsers. - + Solutions: + - If using custom domain: Configure reverse proxy to allow POST requests to `/api/request` + - Alternative: Set `api.playground.disableProxy` in `mint.json` to send requests directly (requires CORS configuration) - + \ No newline at end of file diff --git a/code.mdx b/code.mdx index b137fcc..c1ca019 100644 --- a/code.mdx +++ b/code.mdx @@ -4,36 +4,20 @@ description: "Display inline code and code blocks" icon: 'code' --- -## Basic +## Using Code in Markdown ### Inline Code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` +Use backticks (`) to denote `inline code`. ### Code Block +Use three backticks with an optional language name for syntax highlighting: -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java +```java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` -```` -Visit the [Code Block page](/content/components/code) for more detailed docs. +For more details, visit the [Code Block page](/content/components/code). \ No newline at end of file diff --git a/content/components/accordion-groups.mdx b/content/components/accordion-groups.mdx index 29f9016..33d5fb3 100644 --- a/content/components/accordion-groups.mdx +++ b/content/components/accordion-groups.mdx @@ -4,10 +4,10 @@ description: "Group multiple accordions into a single display." icon: "table-rows" --- -Simply add `` around your existing `` components. +Wrap your existing `` components with `` to create a grouped display. - + You can put other components inside Accordions. ```java HelloWorld.java @@ -17,23 +17,18 @@ Simply add `` around your existing `` components. } } ``` - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - - - + Check out the [Accordion](/content/components/accordions) docs for all the supported props. -````jsx Accordion Group Example +```jsx Accordion Group Example - + You can put other components inside Accordions. ```java HelloWorld.java @@ -43,19 +38,14 @@ Simply add `` around your existing `` components. } } ``` - - - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - + Check out the [Accordion](/content/components/accordions) docs for all the supported props. -```` +``` -`AccordionGroup` does not have any props. +Note: `AccordionGroup` has no configurable props. \ No newline at end of file diff --git a/content/components/callouts.mdx b/content/components/callouts.mdx index 32cc7f0..740f858 100644 --- a/content/components/callouts.mdx +++ b/content/components/callouts.mdx @@ -4,42 +4,19 @@ description: 'Use callouts to add eye-catching context to your content' icon: 'circle-exclamation' --- -### Note Callouts +Our callout components help emphasize important information in your content. Here are the available callout types: -This adds a note in the content +Use Notes for general informational content +Use Warnings for cautionary messages or potential issues +Use Info for additional context and detailed information +Use Tips for helpful suggestions and best practices +Use Check for success messages or completion status -```jsx -This adds a note in the content -``` - -### Warning Callouts - -This raises a warning to watch out for - -```jsx -This raises a warning to watch out for -``` - -### Info Callouts - -This draws attention to important information +### Usage +All callouts follow the same syntax: ```jsx -This draws attention to important information +Your message here ``` -### Tip Callouts - -This suggests a helpful tip - -```jsx -This suggests a helpful tip -``` - -### Check Callouts - -This brings us a checked status - -```jsx -This brings us a checked status -``` +Replace `ComponentName` with any of: `Note`, `Warning`, `Info`, `Tip`, or `Check`. \ No newline at end of file diff --git a/content/components/code.mdx b/content/components/code.mdx index d59351b..e73d8b5 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -6,35 +6,17 @@ icon: "code" -````md Code Block Example ```javascript Code Block Example const hello = "world"; ``` -```` -## Basic Code Block +## Basic Usage -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Use three backticks (```) to create code blocks in markdown. Add a language identifier after the backticks for syntax highlighting, powered by [Prism](https://prismjs.com/#supported-languages). -``` -helloWorld(); -``` - -````md -``` -helloWorld(); -``` -```` - -## Syntax Highlighting - -Put the name of your programming language after the three backticks to get syntax highlighting. - -We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported. - -```java +```java Example with Syntax Highlighting class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); @@ -42,55 +24,28 @@ class HelloWorld { } ``` -````md -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` +## Additional Features -## Names +### Names +Add text after the language identifier to name your code example: -You can add more text after the programming language to set the name of your code example. The text can be anything as long as its all in one line. - -```javascript Code Block Example +```javascript Named Example const hello = "world"; ``` -````md Code Block Example -```javascript Code Block Example -const hello = "world"; -``` -```` - -## Line Highlighting - -You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. +### Line Highlighting +Highlight specific lines using curly braces `{}` with line numbers or ranges: -```javascript Line Highlighting Example {1,3-5} +```javascript Line Highlighting {1,3-4} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); + sayHello(); } -sayHello(); ``` -````md -```javascript Line Highlighting Example {1,3-5} -const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); -} -sayHello(); -``` -```` - -## Code Groups - -Want to display multiple code examples in one code box? Check out the Code Group docs: +### Code Groups +For multiple code examples in one block, see our Code Group component: Read the reference for the Code Group component - + \ No newline at end of file diff --git a/content/components/frames.mdx b/content/components/frames.mdx index 66a24cd..60bc9c1 100644 --- a/content/components/frames.mdx +++ b/content/components/frames.mdx @@ -4,17 +4,9 @@ description: "Use the Frame component to wrap images or other components in a co icon: "frame" --- -Frames are very helpful if you want to center an image. +The Frame component helps center and contain images or other components. You can optionally add captions for additional context. - - - - -## Captions - -You can add additional context to an image using the optional `caption` prop. - - + @@ -32,10 +24,10 @@ You can add additional context to an image using the optional `caption` prop. ``` -```jsx Frame with Captions +```jsx Frame with Caption ``` - + \ No newline at end of file diff --git a/content/components/icons.mdx b/content/components/icons.mdx index ad272ac..68fe793 100644 --- a/content/components/icons.mdx +++ b/content/components/icons.mdx @@ -7,21 +7,12 @@ icon: "icons" - -```jsx Icon Example +```jsx ``` -## Inline Icons - -The icon will be placed inline when used in a paragraph. - -```markdown Inline Icon Example - The documentation you want, effortlessly -``` - - The documentation you want, effortlessly +Inline icons can be used within paragraphs: Like this! ## Props @@ -39,4 +30,4 @@ The icon will be placed inline when used in a paragraph. The size of the icon in pixels - + \ No newline at end of file diff --git a/content/components/mermaid-diagrams.mdx b/content/components/mermaid-diagrams.mdx index 1334bde..4f73913 100644 --- a/content/components/mermaid-diagrams.mdx +++ b/content/components/mermaid-diagrams.mdx @@ -4,70 +4,46 @@ description: 'Display diagrams using Mermaid' icon: 'diagram-project' --- +[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. + -````md Mermaid Flowchart Example +````md Mermaid Example ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end - subgraph subgraph2 - direction TB - top2[top] --> bottom2[bottom] - end - %% ^ These subgraphs are identical, except for the links to them: - - %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 - %% Link *within* subgraph2: - %% subgraph2 inherits the direction of the top-level graph (LR) - outside ---> top2 ``` ```` -[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. - ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end - subgraph subgraph2 - direction TB - top2[top] --> bottom2[bottom] - end - %% ^ These subgraphs are identical, except for the links to them: - - %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 - %% Link *within* subgraph2: - %% subgraph2 inherits the direction of the top-level graph (LR) - outside ---> top2 ``` -You can create the following using Mermaid diagrams: - -- Flowchart -- Sequence diagram -- Class diagram -- State diagram -- Entity relationship diagram -- User journey -- and more - -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). - -## Syntax for Mermaid diagrams - -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. +Supported diagram types include: +- Flowcharts +- Sequence diagrams +- Class diagrams +- State diagrams +- Entity relationship diagrams +- User journeys +- And more +To create a diagram, use the Mermaid code block syntax: ````md ```mermaid // Your mermaid code block here ``` ```` + +For all available diagram types and syntax, visit the [Mermaid website](https://mermaid.js.org/). \ No newline at end of file diff --git a/content/components/params.mdx b/content/components/params.mdx index e9e1249..a47e652 100644 --- a/content/components/params.mdx +++ b/content/components/params.mdx @@ -4,29 +4,21 @@ description: "Set path, query, and body parameters" icon: "text-size" --- -`ParamField` components help define the parameters for your APIs or SDKs. Adding a ParamField will automatically add an [API Playground](/api-playground/overview). - - - An example of a parameter field - +`ParamField` components define parameters for APIs or SDKs and automatically add an [API Playground](/api-playground/overview). -```jsx Path Example - - An example of a parameter field +```jsx Example + + Path parameter example -``` -```jsx Query Example - - The filtering command used to sort through the users + + Query parameter example -``` -```jsx Body Example - The age of the user. Cannot be less than 0 + Body parameter example ``` @@ -35,33 +27,33 @@ icon: "text-size" ## Props - Whether it is a query, path, body, or header parameter followed by the name + Parameter type and name - Expected type of the parameter's value + Expected value type - Indicate whether the parameter is required + Whether parameter is required - Indicate whether the parameter is deprecated + Whether parameter is deprecated - Default value used by the server if the request does not provide a value + Default server value if none provided - Value that will be used to initialize the playground + Playground initialization value - Placeholder text for the input in the playground + Input placeholder text - Description of the parameter (markdown enabled) - + Parameter description (markdown enabled) + \ No newline at end of file diff --git a/content/components/responses.mdx b/content/components/responses.mdx index bde8336..dfa025e 100644 --- a/content/components/responses.mdx +++ b/content/components/responses.mdx @@ -4,22 +4,12 @@ description: 'Display API response values' icon: 'message' --- -The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something. +The `` component defines API return values and can be used to list types in documentation. A response field example - - -```jsx ResponseField Example - - A response field example - -``` - - - ## Props @@ -36,4 +26,4 @@ The `` component is designed to define the return values of an AP Show "required" beside the field name. - + \ No newline at end of file diff --git a/content/components/steps.mdx b/content/components/steps.mdx index 09700a4..1747857 100644 --- a/content/components/steps.mdx +++ b/content/components/steps.mdx @@ -4,7 +4,7 @@ description: 'Sequence content using the Steps component' icon: 'arrow-progress' --- -Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. +Display a series of actions or events in a sequential format. @@ -19,7 +19,6 @@ Steps are the best way to display a series of actions of events to your users. Y - ```jsx Steps Example @@ -33,41 +32,40 @@ Steps are the best way to display a series of actions of events to your users. Y ``` - -## Steps Props +## Props - A list of `Step` components. + List of `Step` components. - The size of the step titles. One of `p`, `h2` and `h3`. + Step title size: `p`, `h2`, or `h3`. -## Individual Step Props +### Step Props - The content of a step either as plain text, or components. + Step content as text or components. - A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` + [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` + Icon type: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, or `brands` - The title is the primary text for the step and shows up next to the indicator. + Primary text displayed next to the step indicator. - The number of the step. + Step number. - The size of the step titles. One of `p`, `h2` and `h3`. - + Step title size: `p`, `h2`, or `h3`. + \ No newline at end of file diff --git a/content/components/sticky-examples.mdx b/content/components/sticky-examples.mdx index b44d3ba..ac03faa 100644 --- a/content/components/sticky-examples.mdx +++ b/content/components/sticky-examples.mdx @@ -4,15 +4,11 @@ description: "Display code blocks at the top-right of the page on desktop device icon: "sidebar-flip" --- -The `` and `` stick code blocks to the top-right of a page even as you scroll. The components work on all pages even if you don't use an API playground. - -`` and `` show up like regular code blocks on mobile. +`` and `` components stick code blocks to the top-right of desktop pages while scrolling, appearing as regular code blocks on mobile devices. ## Request Example -The `` component works similar to [CodeGroup](/content/components/code-groups), but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside ``. - -Please set a name on every code block you put inside RequestExample. +`` works like [CodeGroup](/content/components/code-groups) but displays content in the right sidebar. Add a name for each code block inside. ````md RequestExample Example @@ -29,7 +25,7 @@ Please set a name on every code block you put inside RequestExample. ## Response Example -The `` component is the same as `` but will show up underneath it. +`` functions identically but appears below ``. ````md ResponseExample Example @@ -41,4 +37,4 @@ The `` component is the same as `` but will sho ```` - + \ No newline at end of file diff --git a/content/components/tabs.mdx b/content/components/tabs.mdx index 255920e..2739f65 100644 --- a/content/components/tabs.mdx +++ b/content/components/tabs.mdx @@ -4,8 +4,6 @@ description: 'Toggle content using the Tabs component' icon: 'window-restore' --- -You can add any number of tabs. - ☝️ Welcome to the content that you can only see inside the first Tab. @@ -13,9 +11,6 @@ You can add any number of tabs. ✌️ Here's content that's only inside the second Tab. - - 💪 Here's content that's only inside the third Tab. - @@ -28,9 +23,6 @@ You can add any number of tabs. ✌️ Here's content that's only inside the second Tab. - - 💪 Here's content that's only inside the third Tab. - ``` @@ -39,5 +31,5 @@ You can add any number of tabs. ## Tab Props - The title of the tab. Short titles are easier to navigate. - + The title of the tab + \ No newline at end of file diff --git a/content/components/update.mdx b/content/components/update.mdx index f2bad58..68346b3 100644 --- a/content/components/update.mdx +++ b/content/components/update.mdx @@ -7,40 +7,20 @@ icon: "rectangle-history" The `Update` component is used to keep track of changes and updates. - - - - - ## Changelog - - You can add anything here, like a screenshot, a code snippet, or a list of changes. - - #### Features - Responsive design - Sticky section for each changelog - ### How to use ```md - This is how you use a changelog with a label - and a description. - - - This is how you use a changelog with a label - and a description. + Add your changelog content here ``` - - You can use multiple `Update` components to create changelogs. - Each `label` creates an anchor and also shows up on the table of contents on the right. + Each `label` creates an anchor and appears in the table of contents. ## Props @@ -50,5 +30,5 @@ The `Update` component is used to keep track of changes and updates. - Description below the label in the Changelog preview. - + Description below the label. + \ No newline at end of file diff --git a/development.mdx b/development.mdx index 1558101..9d15df6 100644 --- a/development.mdx +++ b/development.mdx @@ -4,99 +4,53 @@ description: 'Preview changes locally to update your docs' --- - -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - +**Prerequisite**: Node.js (version 19 or higher) -**Step 1**: Install Mintlify: +## Quick Setup +1. Install Mintlify: - - ```bash npm - npm i -g mintlify - ``` - +```bash npm +npm i -g mintlify +``` ```bash yarn yarn global add mintlify ``` - -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: - +2. Run the dev server: ```bash mintlify dev ``` +Your docs will be available at `http://localhost:3000`. -A local preview of your documentation will be available at `http://localhost:3000`. - -### Custom Ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +## Common Commands ```bash -mintlify dev --port 3333 -``` - -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` - -## Mintlify Versions - -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: - - - - ```bash npm - npm i -g mintlify@latest - ``` +# Run on custom port +mintlify dev --port -```bash yarn -yarn global upgrade mintlify -``` - - - -## Validating Links - -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: - -```bash +# Check for broken links mintlify broken-links -``` -## Deployment - -If the deployment is successful, you should see the following: - - - - - -## Code Formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. +# Update CLI +npm i -g mintlify@latest # or yarn global upgrade mintlify +``` ## Troubleshooting - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` + + 1. Remove mintlify: `npm remove -g mintlify` + 2. Upgrade to Node v19+ + 3. Reinstall: `npm install -g mintlify` - - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + Delete ~/.mintlify folder and run `mintlify dev` again. + +## Development Tools +- [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) - Syntax highlighting +- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting \ No newline at end of file diff --git a/image-embeds.mdx b/image-embeds.mdx index 5c12f77..cc4f757 100644 --- a/image-embeds.mdx +++ b/image-embeds.mdx @@ -4,146 +4,51 @@ description: 'Add image, video, and other HTML elements' icon: 'image' --- - - - Mintlify supports files up to 5 MB. To use larger files, consider a storage - service like Cloudinary and embed in your Mintlify documentation. + Mintlify supports files up to 5 MB. For larger files, use services like Cloudinary. -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code +## Images +### Markdown Syntax ```md ![title](/path/image.jpg) ``` -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using Embeds - -To get more customizability with images, you can also use embeds to add images. - +### HTML Embed ```html ``` -### Disable Image Zoom - -To disable the default zoom on click for images, add the noZoom property to image embeds. - -```html - -``` - -### Linking Images - -To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor. - -```html - - - -``` - -### Dark Mode - -To use separate images for light and dark mode, use Tailwind CSS to hide and show images. - +### Key Features +- Disable zoom: Add `noZoom` property +- Link images: Wrap in `` tags +- Dark mode support: ```html - - + + ``` -### Related - -For more information, we recommend the following sections: - - - Read the reference for the Frame component - - ## Videos - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -For YouTube videos use: - +### YouTube Embed ```html ``` -For other videos, use: - +### Custom Video ```html ``` -To autoplay the video, use: - -```html - -``` - - -Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to -be written in camelCase: autoPlay, playsInline. - - -## iFrames - -Loads another HTML page within the document. - -```html - -``` - - Although not required, we recommend adding the `alt` and `title` attributes to - images for better SEO and accessability. Learn more at [image - SEO](https://yoast.com/image-seo-alt-tag-and-title-tag-optimization/). - + Add `alt` and `title` attributes to images for better SEO and accessibility. + \ No newline at end of file diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe16..2a96741 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,27 +2,18 @@ title: "Google Analytics 4" --- -You will need to generate a new GA4 property to use with Mintlify. The data collected will go into the same project as your other Google Analytics data. +Generate a new GA4 property to use with Mintlify. This works with both new GA4 properties and if you're migrating from Universal Analytics. -If you are using the old version of Google Analytics, Universal Analytics, you will still be able to generate a GA4 property. GA4 data is slightly different from UA data but still gets collected in the same project. +## Setup Instructions -## How to Connect GA4 to Mintlify - -### Create a Web Stream - -You will need to create a web stream to get the Measurement ID to put into Mintlify. - -Click the cog at the bottom left of the Google Analytics screen. Then click on Data Streams. +1. Create a web stream in GA4: + - Go to Settings (cog icon) → Data Streams + - Click "Add Stream" → Web + - Enter your Mintlify docs URL ![](/images/ga4-web-streams.png) -Create a Web Stream and put the URL of your Mintlify docs site as the stream URL. - -Your Measurement ID looks like `G-XXXXXXX` and will show up under Stream Details immediately after you create the Web Stream. - -### Put Measurement ID in mint.json - -Add your Measurement ID to your `mint.json` file like so: +2. Add your Measurement ID (`G-XXXXXXX`) to `mint.json`: ```json mint.json "analytics": { @@ -32,14 +23,10 @@ Add your Measurement ID to your `mint.json` file like so: } ``` -### Wait - -Google Analytics takes two to three days to show your data. +3. Wait 2-3 days for data to appear in Google Analytics. -You can use the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to check analytics are enabled correctly. The extension will log to your browser's console every time GA4 makes a request. +Verify setup using the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) Chrome extension. - Preview links have analytics turned off. - - + \ No newline at end of file diff --git a/integrations/analytics/google-tag-manager.mdx b/integrations/analytics/google-tag-manager.mdx index 0e715d0..28e1767 100644 --- a/integrations/analytics/google-tag-manager.mdx +++ b/integrations/analytics/google-tag-manager.mdx @@ -2,9 +2,7 @@ title: "Google Tag Manager" --- -Add your tag ID to `mint.json` file and we'll inject the Google Tag Manager script to all your pages. - -You are responsible for setting up cookie consent banners with Google Tag Manager if you need them. +Add your GTM tag ID to `mint.json` to enable Google Tag Manager on all pages. Note: You are responsible for implementing cookie consent banners if needed. @@ -24,4 +22,4 @@ You are responsible for setting up cookie consent banners with Google Tag Manage } ``` - + \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index dff95d3..0948f4c 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -4,520 +4,30 @@ description: "Integrate with an analytics platform to track viewer events" --- - - - - }> - - - - - - - - } -> - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> - + }> + }> + }> + }> ## Enabling Analytics -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +Add your analytics keys in `mint.json` using the syntax below. You can include multiple integrations. -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. - - - -```json Analytics options in mint.json +```json "analytics": { "amplitude": { "apiKey": "required" }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, "ga4": { "measurementId": "required" }, - "gtm": { - "tagId": "required" - }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" - }, "mixpanel": { "projectToken": "required" - }, - "pirsch": { - "id": "required" - }, - "plausible": { - "domain": "required" - }, - "posthog": { - "apiKey": "required", - "apiHost": "optional" - }, -} -``` - -```json Google Analytics 4 Example -"analytics": { - "ga4": { - "measurementId": "G-XXXXXXX" } + // Add other platforms as needed } ``` - \ No newline at end of file +See the [full list of supported platforms](https://mintlify.com/docs/integrations/analytics) and their configuration options. + \ No newline at end of file diff --git a/integrations/analytics/plausible.mdx b/integrations/analytics/plausible.mdx index 4d47884..1fe0a57 100644 --- a/integrations/analytics/plausible.mdx +++ b/integrations/analytics/plausible.mdx @@ -2,24 +2,11 @@ title: "Plausible" --- -Add your site's domain to `mint.json` to send analytics to Plausible. - - - - Do not include `http://` or `https://` with your domain. - +Add your site's domain (without `http://` or `https://`) to `mint.json` for Plausible analytics: -```json Analytics options in mint.json -"analytics": { - "plausible": { - "domain": "required" - } -} -``` - -```json Example +```json mint.json "analytics": { "plausible": { "domain": "docs.domain.com" @@ -28,3 +15,4 @@ Add your site's domain to `mint.json` to send analytics to Plausible. ``` + \ No newline at end of file diff --git a/integrations/analytics/posthog.mdx b/integrations/analytics/posthog.mdx index b78cabb..2811a4f 100644 --- a/integrations/analytics/posthog.mdx +++ b/integrations/analytics/posthog.mdx @@ -2,37 +2,23 @@ title: "PostHog" --- -Add the following to your `mint.json` file to send analytics to PostHog. - -You only need to include `apiHost` if you are self-hosting PostHog. We send events to `https://app.posthog.com` by default. +Add PostHog analytics configuration to your `mint.json`: -```json Analytics options in mint.json +```json mint.json "analytics": { "posthog": { "apiKey": "required", - "apiHost": "optional" - } -} -``` - -```json Example -"analytics": { - "posthog": { - "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW" + "apiHost": "optional" // Defaults to https://app.posthog.com } } ``` -
- - Enabling PostHog analytics will disable the analytics on the Mintlify dashboard. + Enabling PostHog analytics will disable the Mintlify dashboard analytics. -## Session Recordings - -You need to add the URL for your docs website to Posthog's "Authorized domains for recordings" before you can receive session recordings. The option to add your URL is in Posthog's project settings. +For session recordings, add your docs website URL to PostHog's "Authorized domains for recordings" in project settings. \ No newline at end of file diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d..e9a16c9 100644 --- a/integrations/privacy/osano.mdx +++ b/integrations/privacy/osano.mdx @@ -2,11 +2,11 @@ title: "Osano" --- -Add the following to your `mint.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. +To add the [Osano](https://www.osano.com/) cookie consent manager, add the following to your `mint.json`: -```json Integration options in mint.json +```json mint.json "integrations": { "osano": "SOURCE" } @@ -20,8 +20,4 @@ Add the following to your `mint.json` file to add the [Osano](https://www.osano. -The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`. - -```html Code snippet from Osano -