From 800cc000eb6cbd9c5530b1ed8b266ac193aca424 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 05:31:35 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- advanced/subpath/cloudflare.mdx | 30 +- advanced/subpath/route53-cloudfront.mdx | 2 +- advanced/user-auth/oauth.mdx | 56 +- advanced/user-auth/shared-session.mdx | 69 ++- advanced/widget/chat.mdx | 94 +--- api-playground/mdx/configuration.mdx | 39 +- api-playground/openapi/setup.mdx | 142 +---- api-playground/openapi/writing-openapi.mdx | 36 +- code.mdx | 28 +- content/components/accordion-groups.mdx | 42 +- content/components/code.mdx | 82 +-- content/components/mermaid-diagrams.mdx | 59 +-- development.mdx | 83 +-- integrations/analytics/google-analytics.mdx | 37 +- integrations/analytics/overview.mdx | 555 +++----------------- integrations/analytics/pirsch.mdx | 16 +- integrations/analytics/posthog.mdx | 26 +- integrations/privacy/osano.mdx | 16 +- integrations/sdks/speakeasy.mdx | 52 +- integrations/sdks/stainless.mdx | 25 +- migration.mdx | 135 +---- mint.json | 19 +- quickstart.mdx | 194 ++----- reusable-snippets.mdx | 120 +---- settings/authentication.mdx | 79 +-- settings/gitlab.mdx | 107 +--- 26 files changed, 483 insertions(+), 1660 deletions(-) diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 763b44eda..f0ff21094 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -7,22 +7,16 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; -## Create Cloudflare Worker +## Setup Steps -Navigate to the `Workers & Pages > Create application > Create worker`. You -should be able to presented with the following screen where you can create a new -Cloudlfare worker. +1. Create a new Cloudflare Worker at `Workers & Pages > Create application > Create worker` Create a Cloudflare worker -### Add custom domain - -Once the worker is created, click `Configure worker`. Navigate to the worker -`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain -into the list - we recommend you add both the version with and without `www.` -prepended to the domain. +2. Add your custom domain by going to `Settings > Triggers > Add Custom Domain` + - Add both `domain.com` and `www.domain.com` versions -If you have trouble setting up a custom subdirectory, -[contact our support team](mailto:sales@mintlify.com) and we'll walk you through -upgrading your hosting with us. - -### Edit Worker Script - -Click on `Edit Code` and add the following script into the worker's code. +3. Click `Edit Code` and paste the following script: Cloudflare edit code - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. + Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` in `DOCS_URL` and `CUSTOM_URL` with your values ```javascript @@ -80,5 +67,6 @@ async function handleRequest(request) { } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +4. Click `Deploy` (changes may take a few hours to propagate) + +Need help? [Contact our support team](mailto:sales@mintlify.com) \ No newline at end of file diff --git a/advanced/subpath/route53-cloudfront.mdx b/advanced/subpath/route53-cloudfront.mdx index e181941d2..bf5443986 100644 --- a/advanced/subpath/route53-cloudfront.mdx +++ b/advanced/subpath/route53-cloudfront.mdx @@ -142,4 +142,4 @@ Click `Create records`. You may need to remove the existing A record if one currently exists. -And voila! You should be able to have your documentation served at `/docs` for your primary domain. +And voila! You should be able to have your documentation served at `/docs` for your primary domain. \ No newline at end of file diff --git a/advanced/user-auth/oauth.mdx b/advanced/user-auth/oauth.mdx index 98251eb9f..ab74998e7 100644 --- a/advanced/user-auth/oauth.mdx +++ b/advanced/user-auth/oauth.mdx @@ -1,41 +1,39 @@ --- title: 'OAuth 2.0' -description: 'Integrate with your OAuth server to enable user login via the PKCE flow' +description: 'Enable user login via OAuth PKCE flow' --- -If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. +Mintlify supports authentication through OAuth 2.0 PKCE flow. Here's how to set it up: -## Implementation +## Setup Steps - - Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](./sending-data) format. Take note of the scope or scopes required to access this endpoint. + + Create an API endpoint accessible with an OAuth token that returns user data in the [UserInfo](./sending-data) format. - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select the OAuth option, and fill out the required fields: - - - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters. - - **Client ID**: An ID for the OAuth 2.0 client to be used. - - **Scopes**: An array of scopes that will be requested. - - **Token URL**: The base URL for the token exchange request. - - **Info API URL**: The endpoint that will be hit to retrieve user info. + + In your [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select OAuth and provide: + - Authorization URL + - Client ID + - Required scopes + - Token URL + - Info API URL - - Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server. + + Add the Redirect URL from your Mintlify dashboard to your OAuth server's authorized redirects. -## Example - -I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`. - -To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification. - -I then go to the Mintlify dashboard settings, navigate to the User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: -- **Authorization URL**: `https://auth.foo.com/authorization` -- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` -- **Scopes**: `['docs-user-info']` -- **Token URL**: `https://auth.foo.com/exchange` -- **Info API URL**: `https://api.foo.com/docs/user-info` - -Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings. +## Example Configuration + +```json +{ + "Authorization URL": "https://auth.foo.com/authorization", + "Client ID": "ydybo4SD8PR73vzWWd6S0ObH", + "Scopes": ["docs-user-info"], + "Token URL": "https://auth.foo.com/exchange", + "Info API URL": "https://api.foo.com/docs/user-info" +} +``` + + \ No newline at end of file diff --git a/advanced/user-auth/shared-session.mdx b/advanced/user-auth/shared-session.mdx index d2925a269..4eab59b6c 100644 --- a/advanced/user-auth/shared-session.mdx +++ b/advanced/user-auth/shared-session.mdx @@ -1,50 +1,49 @@ --- title: 'Shared Session Auth' -description: 'Seamlessly share user sessions between your dashboard and your docs' +description: 'Share user sessions between your dashboard and docs' --- -This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. +Shared Session Authentication lets you use existing session data from your user's browser to authenticate your documentation. -## Implementation +## Setup - - Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./sending-data) format. - - If the API domain does not *exactly match* the docs domain: - - Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`) - - Ensure your API’s `Access-Control-Allow-Credentials` header is `true` - - These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints. - + + Create an API endpoint that: + - Uses your existing session authentication + - Returns user data in the [UserInfo](./sending-data) format + - Includes proper CORS headers if your API and docs domains differ: + ```text + Access-Control-Allow-Origin: your-docs-domain.com + Access-Control-Allow-Credentials: true + ``` + + + Only enable these CORS settings on your user info endpoint, not across all API routes. + - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings. + + Add your API URL and Login URL in your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication). -## Examples +## Example Setup -### Dashboard at subdomain, docs at subdomain +Your setup will depend on where your dashboard and docs are hosted: -I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`. +- **Different Subdomains**: For dashboard at `dash.example.com` and docs at `docs.example.com` + ```text + API Endpoint: https://dash.example.com/api/docs/user-info + CORS Origin: https://docs.example.com + ``` -To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. +- **Dashboard Subdomain, Docs at Root**: For dashboard at `dash.example.com` and docs at `example.com/docs` + ```text + API Endpoint: https://dash.example.com/api/docs/user-info + CORS Origin: https://example.com + ``` -I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. - -### Dashboard at subdomain, docs at root - -I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. - -To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. - -I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. - -### Dashboard at root, docs at root - -I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. - -To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. - -I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field. \ No newline at end of file +- **Same Domain**: For dashboard at `example.com/dashboard` and docs at `example.com/docs` + ```text + API Endpoint: https://example.com/api/docs/user-info + ``` \ No newline at end of file diff --git a/advanced/widget/chat.mdx b/advanced/widget/chat.mdx index 216179a7a..15829832c 100644 --- a/advanced/widget/chat.mdx +++ b/advanced/widget/chat.mdx @@ -2,19 +2,17 @@ title: "Chat Widget" --- -Integrate the Mintlify widget into your products to offer users quick access to AI-powered chat with your docs content as the knowledge base. +Integrate the Mintlify chat widget into your products to provide AI-powered search through your documentation. ![widget](https://mintlify-assets.b-cdn.net/widget/hero.webp) -## Getting started +## Setup -First, generate an API key in [the Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth). +1. Generate an API key in the [Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth) +2. Add the widget to your site: -![widget](https://mintlify-assets.b-cdn.net/widget/key.webp) - -## Installation - -Add the widget by adding these script tags into your site's `...` tag. +### HTML Sites +Add to your site's `` tag: ```html ``` -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/Next.js +Install and use the widget component: ```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 can be customized using the following props: -#### MintlifyWidgetDisplayChatProps +| Prop | Description | +| ------------ | ---------------------------------------------------------- | +| `connection` | API connection settings (required) | +| `display` | Widget appearance and interaction settings | +| `tracking` | Analytics tracking callbacks | -| 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` display +- **Colors**: Customize primary colors for light/dark modes +- **Chat Settings**: Configure example queries and citation behavior -| 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, visit our [API Reference](https://mintlify.com/docs/api-reference/introduction). \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df30..3ea51803b 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -1,27 +1,26 @@ --- title: 'MDX Setup' -description: 'Generate docs pages for your API endpoints using MDX' +description: 'Generate API documentation with 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 helps you create interactive API documentation using MDX files and the `mint.json` configuration. This setup enables API playground functionality, request examples, and response examples. - - In your `mint.json` file, define your base URL and auth method: + + Add your API configuration to `mint.json`: ```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 API 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 configuration options in our [reference guide](/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 the following frontmatter: ```md --- @@ -46,20 +44,17 @@ 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} + Use `{parameterName}` for path parameters: + ``` + https://api.example.com/v1/users/{userId} ``` - - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. - + With `baseUrl` configured, you can use relative paths like `/v1/users` - - 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 about navigation [here](/settings/navigation). - + \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 7d45da4f6..64700b850 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -3,20 +3,21 @@ title: "OpenAPI Setup" description: "Reference OpenAPI endpoints in your docs pages" --- -## Add an OpenAPI specification file +## Add Your OpenAPI Specification -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+. +To get started, you'll need a valid OpenAPI document (version 3.0+) in either JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). -## Auto-populate API pages +## Configure Your Documentation -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. +There are two main ways to add OpenAPI documentation: -**Example with Anchors:** +### 1. Auto-generate API Pages (Recommended) -```json {5} +The simplest way to get started is to add an `openapi` field to your `mint.json`. This can be either: +- A path to your OpenAPI file in your docs repo +- A URL to a hosted OpenAPI document + +```json { "anchors": [ { @@ -29,121 +30,22 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -![](/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" - } - ] -} -``` - -![](/images/autogeneration-with-tabs.png) +Mintlify will automatically generate pages for each API endpoint. -When using this option, the metadata for the generated pages will have the following default values: +### 2. Create Custom API Pages -* `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 - -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. - -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 -``` +For more customization, you can create individual MDX pages for your API endpoints: -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. - -```bash -npx @mintlify/scraping@latest openapi-file -o api-reference +```md +--- +title: "Get users" +openapi: "GET /users" +--- ``` -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. - -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. - - - ```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 - -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: - - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` - - ```md Format - --- - openapi-schema: "schema-key" - --- + For large APIs, you can auto-generate MDX files using our scraping tool: + ```bash + npx @mintlify/scraping@latest openapi-file -o api-reference ``` - \ No newline at end of file + \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 57cd93680..ab06625fc 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -3,30 +3,20 @@ title: "Writing OpenAPI" description: "Use OpenAPI features to enhance your Mintlify docs" --- -## Describing your API +## Getting Started with OpenAPI -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 +To use OpenAPI in your Mintlify documentation, you'll need to focus on two main components: - - 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). - - -## Specifying the URL for your API - -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/). - -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. +1. **Base URL Configuration** +- Add a `servers` field to specify your API's base URL +- This enables the API Playground feature +- Without a server URL, the API Playground will run in simple mode -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. +2. **Authentication Setup** +- Define your authentication methods using `securitySchemes` +- Common types include Basic, Bearer, and API Keys +- Apply authentication using the `security` field -## 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 OpenAPI syntax and examples, we recommend using [Swagger's Editor](https://editor.swagger.io/) and referring to the [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md). + \ No newline at end of file diff --git a/code.mdx b/code.mdx index b137fcce0..475754ab1 100644 --- a/code.mdx +++ b/code.mdx @@ -4,36 +4,20 @@ description: "Display inline code and code blocks" icon: 'code' --- -## Basic +## Inline Code -### Inline Code +Use backticks (`) to show `inline code`. -To denote a `word` or `phrase` as code, enclose it in backticks (`). +## Code Blocks -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -### Code Block - -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!"); - } -} -``` +Use three backticks with an optional language name for syntax highlighting: -````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, see 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 29f90169c..916763d4e 100644 --- a/content/components/accordion-groups.mdx +++ b/content/components/accordion-groups.mdx @@ -4,58 +4,32 @@ description: "Group multiple accordions into a single display." icon: "table-rows" --- -Simply add `` around your existing `` components. +Simply wrap multiple `` components with `` to group them together. - + You can put other components inside Accordions. - - ```java HelloWorld.java - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - - 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 - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - - - - 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` does not have any props. \ No newline at end of file diff --git a/content/components/code.mdx b/content/components/code.mdx index d59351bb4..0f01f13a8 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -6,96 +6,46 @@ icon: "code" -````md Code Block Example -```javascript Code Block Example +```javascript const hello = "world"; ``` -```` -## Basic Code Block +## Code Block Basics -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Create code blocks by enclosing code in three backticks (\`\`\`). Add a language name after the backticks for syntax highlighting. +```javascript +const greeting = "Hello, World!"; +console.log(greeting); ``` -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 -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` - -## Names -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. +We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. View all supported languages in the [Prism test drive](https://prismjs.com/test.html#language=markup). -```javascript Code Block Example -const hello = "world"; -``` +## Additional Features -````md Code Block Example -```javascript Code Block Example +- **Names**: Add text after the language name for a title +```javascript Example Code 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. - -```javascript Line Highlighting Example {1,3-5} +- **Line Highlighting**: Use `{1,3-5}` syntax to highlight specific lines +```javascript {1,3} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } -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: +## Related Components - Read the reference for the Code Group component + Display multiple code examples in one code box + + \ No newline at end of file diff --git a/content/components/mermaid-diagrams.mdx b/content/components/mermaid-diagrams.mdx index 1334bde52..982fae25e 100644 --- a/content/components/mermaid-diagrams.mdx +++ b/content/components/mermaid-diagrams.mdx @@ -4,9 +4,8 @@ description: 'Display diagrams using Mermaid' icon: 'diagram-project' --- - +[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. Here's an example of what you can create: -````md Mermaid Flowchart Example ```mermaid flowchart LR subgraph subgraph1 @@ -17,57 +16,29 @@ icon: 'diagram-project' 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: +## Types of Diagrams -- Flowchart -- Sequence diagram -- Class diagram -- State diagram -- Entity relationship diagram -- User journey -- and more +You can create various types of diagrams including: +- Flowcharts +- Sequence diagrams +- Class diagrams +- State diagrams +- Entity relationship diagrams +- User journey diagrams +- And more -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). +Visit the [Mermaid website](https://mermaid.js.org/) for a complete list of supported diagrams. -## Syntax for Mermaid diagrams +## How to Use -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. +To create a Mermaid diagram, simply write your diagram code within a Mermaid code block: ````md ```mermaid -// Your mermaid code block here +// Your mermaid code here ``` -```` +```` \ No newline at end of file diff --git a/development.mdx b/development.mdx index 15581014c..714cdcd2f 100644 --- a/development.mdx +++ b/development.mdx @@ -4,99 +4,64 @@ 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 Start +1. Install Mintlify CLI: - - ```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. Go to your docs directory and run: ```bash mintlify dev ``` -A local preview of your documentation will be available at `http://localhost:3000`. +Your docs 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 Tasks +### Change Port +Use `--port` flag to run on a different port: ```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: - +### Update Mintlify +Keep your CLI up to date with: - - ```bash npm - npm i -g mintlify@latest - ``` +```bash npm +npm i -g mintlify@latest +``` ```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: - +### Check for Broken Links ```bash 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. - ## 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. - + \ No newline at end of file diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe1610..36f6fa65e 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,27 +2,19 @@ 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. +To use Google Analytics with Mintlify, you'll need a GA4 property. This works with both new GA4 projects and existing Universal Analytics setups. -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. +## Quick Setup -## 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 Google Analytics: + - Go to Settings (cog icon) → Data Streams + - Click "Add Stream" → Web + - Enter your Mintlify docs URL + - Copy the Measurement ID (`G-XXXXXXX`) ![](/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 the Measurement ID to your `mint.json`: ```json mint.json "analytics": { @@ -32,14 +24,9 @@ Add your Measurement ID to your `mint.json` file like so: } ``` -### Wait - -Google Analytics takes two to three days to show your data. - -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. +3. Wait 2-3 days for data to appear in Google Analytics. - -Preview links have analytics turned off. - - +- Preview links have analytics disabled +- Use [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to verify setup + \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index dff95d35a..7b63d0fce 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -12,512 +12,99 @@ description: "Integrate with an analytics platform to track viewer events" }> - + Connect to Amplitude + - - - - - - } -> - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - + - - + + + + - - - - - + } + > + Connect to Google Analytics 4 + + + - - - - - - - - - - + + + - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> + } + > + Connect to Mixpanel + + + View additional analytics options + -## Enabling Analytics - -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. - -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +## Enable Analytics - +Add your analytics keys to `mint.json`. Here's the basic syntax: -```json Analytics options in mint.json -"analytics": { - "amplitude": { - "apiKey": "required" - }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, +```json +{ + "analytics": { "ga4": { - "measurementId": "required" - }, - "gtm": { - "tagId": "required" + "measurementId": "G-XXXXXXX" }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" + "amplitude": { + "apiKey": "xxx" }, "mixpanel": { - "projectToken": "required" - }, - "pirsch": { - "id": "required" - }, - "plausible": { - "domain": "required" - }, - "posthog": { - "apiKey": "required", - "apiHost": "optional" - }, -} -``` - -```json Google Analytics 4 Example -"analytics": { - "ga4": { - "measurementId": "G-XXXXXXX" + "projectToken": "xxx" } + } } ``` - \ No newline at end of file +Additional supported platforms include: +- Plausible +- PostHog +- HotJar +- Fathom +- Google Tag Manager +- LogRocket +- Clearbit +- Pirsch +- Koala +- Heap +- Segment + +Visit the individual integration pages to learn more about configuring each analytics platform. \ No newline at end of file diff --git a/integrations/analytics/pirsch.mdx b/integrations/analytics/pirsch.mdx index e4b3e3085..58561ba3a 100644 --- a/integrations/analytics/pirsch.mdx +++ b/integrations/analytics/pirsch.mdx @@ -2,13 +2,11 @@ title: "Pirsch" --- -Add the following to your `mint.json` file to send analytics to Pirsch. - -You can get your site ID from Settings \> Developer \> Identification Code. +To enable Pirsch analytics, add your site ID to your `mint.json` file: -```json Analytics options in mint.json +```json mint.json "analytics": { "pirsch": { "id": "required" @@ -16,12 +14,6 @@ You can get your site ID from Settings \> Developer \> Identification Code. } ``` -```json Example -"analytics": { - "pirsch": { - "id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp" - } -} -``` - + +You can find your site ID in Pirsch under Settings > Developer > Identification Code. \ No newline at end of file diff --git a/integrations/analytics/posthog.mdx b/integrations/analytics/posthog.mdx index b78cabb18..5a170530b 100644 --- a/integrations/analytics/posthog.mdx +++ b/integrations/analytics/posthog.mdx @@ -2,37 +2,27 @@ 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. +To enable PostHog analytics, add the following configuration to your `mint.json`: -```json Analytics options in mint.json -"analytics": { +```json mint.json +{ + "analytics": { "posthog": { - "apiKey": "required", - "apiHost": "optional" - } -} -``` - -```json Example -"analytics": { - "posthog": { - "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW" + "apiKey": "required", + "apiHost": "optional" // Only needed for self-hosted PostHog } + } } ``` -
- Enabling PostHog analytics will disable the analytics on the Mintlify dashboard. ## 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. +To enable session recordings, add your docs website URL to "Authorized domains for recordings" in your PostHog project settings. \ No newline at end of file diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d59..4255b859b 100644 --- a/integrations/privacy/osano.mdx +++ b/integrations/privacy/osano.mdx @@ -2,26 +2,16 @@ 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 your Osano source URL to `mint.json`: -```json Integration options in mint.json +```json mint.json "integrations": { "osano": "SOURCE" } ``` -```json Example -"integrations": { - "osano": "https://cmp.osano.com/2sUB2dqwqdkks/8dqwd-dwd86£-4a9b/osano.js" -} -``` - -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 -