From 2f067259286557d6a2ac7da3211747ce88b5eaf5 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:30:40 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- advanced/subpath/cloudflare.mdx | 54 +- advanced/user-auth/overview.mdx | 81 +-- advanced/user-auth/shared-session.mdx | 58 +-- advanced/widget/chat.mdx | 92 +--- api-playground/mdx/configuration.mdx | 33 +- api-playground/openapi/setup.mdx | 143 ++---- api-playground/openapi/writing-openapi.mdx | 34 +- code.mdx | 24 +- content/components/accordion-groups.mdx | 38 +- content/components/code.mdx | 75 +-- content/components/mermaid-diagrams.mdx | 59 +-- integrations/analytics/google-analytics.mdx | 35 +- integrations/analytics/hotjar.mdx | 6 +- integrations/analytics/overview.mdx | 525 +------------------- integrations/privacy/osano.mdx | 18 +- integrations/sdks/speakeasy.mdx | 55 +- integrations/sdks/stainless.mdx | 26 +- migration.mdx | 129 +---- mint.json | 19 +- quickstart.mdx | 194 ++------ 20 files changed, 340 insertions(+), 1358 deletions(-) diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 763b44ed..40f7b0b4 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -7,46 +7,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; -## Create Cloudflare Worker +## Setup Instructions -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 Cloudflare Worker at `Workers & Pages > Create application > Create worker` - - Create a Cloudflare worker - +2. Add your custom domain: + - Go to `Configure worker > Settings > Triggers` + - Click `Add Custom Domain` + - Add your domain (with and without `www.`) -### 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. - - - Cloudflare worker custom domain - - -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. - - - Cloudflare edit code - - - - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. - +3. Add the worker script: + - Click `Edit Code` + - Copy the script below + - Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values + - Deploy the changes ```javascript addEventListener("fetch", (event) => { @@ -56,9 +30,7 @@ addEventListener("fetch", (event) => { async function handleRequest(request) { try { const urlObject = new URL(request.url); - // If the request is to the docs subdirectory if (/^\/docs/.test(urlObject.pathname)) { - // Then Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; const CUSTOM_URL = "[YOUR_DOMAIN]"; @@ -74,11 +46,9 @@ async function handleRequest(request) { return await fetch(proxyRequest); } } catch (error) { - // if no action found, play the regular request return await fetch(request); } } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +Need help? [Contact our support team](mailto:sales@mintlify.com) for assistance with custom subdirectory setup. \ No newline at end of file diff --git a/advanced/user-auth/overview.mdx b/advanced/user-auth/overview.mdx index c4d4da70..c13733c5 100644 --- a/advanced/user-auth/overview.mdx +++ b/advanced/user-auth/overview.mdx @@ -1,88 +1,53 @@ --- title: 'Introduction' -description: 'Give your users a personalized docs experience' +description: 'Personalize your docs with User Auth' --- -User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. Your users. +User Auth lets you identify and authenticate users to create personalized documentation experiences. -Example use cases: +## Key Features -1. **Customize MDX content** with a user's information, such as their name, plan, or title. +1. **Custom Content** - Display user-specific information like names and plan details +2. **API Integration** - Auto-fill API keys in the API Playground +3. **Access Control** - Show/hide pages based on user groups -2. **Prefill API keys** in the API Playground for streamlined use. +## What User Auth Is Not -3. **Selectively show pages** in the navigation based on a user's groups. +1. **Not for Private Docs** - Pages remain accessible via direct URLs +2. **Not a User Database** - Mintlify doesn't store user data -## What *isn't* User Auth +Need private docs? [Contact our team](mailto:sales@mintlify.com) for solutions. -At this time, User Auth is not meant for the following use cases: +## Using User Auth -1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it. +### Personalizing Content -2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data. - -If you are interested in private docs content, [contact our team](mailto:sales@mintlify.com) to explore solutions. - -## How to Use - -### Customizing MDX Content - -When writing content, you can use the `userContext` variable to access the information you have sent to your docs. Here's a simple example: - -Hello, {userContext.name ?? 'reader'}! +Access user information through the `userContext` variable: ```jsx Hello, {userContext.name ?? 'reader'}! ``` -This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan: - -User Auth is an enterprise feature. { -userContext.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. -: userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} - -```jsx -User Auth is an enterprise feature. { - userContext.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. - : userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} -``` - - The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}` + Always use optional chaining (e.g., `userContext.org?.plan`) since `userContext` is empty (`{}`) for logged-out users. -### Prefilling API Keys +### API Key Integration -If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. +API Playground inputs are automatically prefilled when matching field names are provided in the user info. -### Showing/Hiding Pages +### Page Visibility Control -By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. -When determining which pages to show to the user, Mintlify will check which groups the user belongs to. -If the user is not in any of the groups listed in the page metadata, the page will not be shown. +Control page visibility using the `groups` field in page metadata: ```md --- -title: 'Managing Your Users' -description: 'Adding and removing users from your organization' +title: 'Example Page' groups: ['admin'] --- ``` -Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata: - -| | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo | -| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: | -| `groups` not in metadata | ✅ | ✅ | ✅ | -| `groups: []` in metadata | ❌ | ❌ | ❌ | -| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | - -Note that an empty array in the page metadata is interpreted as "No groups should see this page." \ No newline at end of file +Page visibility rules: +- No `groups` in metadata: Visible to all +- Empty `groups` array: Hidden from all +- Specific groups: Only visible to users in those groups \ No newline at end of file diff --git a/advanced/user-auth/shared-session.mdx b/advanced/user-auth/shared-session.mdx index d2925a26..a824b672 100644 --- a/advanced/user-auth/shared-session.mdx +++ b/advanced/user-auth/shared-session.mdx @@ -3,48 +3,40 @@ title: 'Shared Session Auth' description: 'Seamlessly share user sessions between your dashboard and your docs' --- -This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. +Share your existing user sessions between your dashboard and documentation for a seamless experience. ## Implementation - 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 session authentication to identify users and returns a JSON payload following the [UserInfo](./sending-data) format. + + If your API domain differs from your docs domain: + - Add your docs domain to `Access-Control-Allow-Origin` header + - Set `Access-Control-Allow-Credentials` header to `true` + + + Only enable these CORS settings on the user info endpoint, not all dashboard endpoints. + - - 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 Configurations -### Dashboard at subdomain, docs at subdomain +1. **Dashboard and docs on different subdomains** + - Dashboard: `dash.foo.com` + - Docs: `docs.foo.com` + - API Endpoint: `dash.foo.com/api/docs/user-info` -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`. +2. **Dashboard on subdomain, docs on root** + - Dashboard: `dash.foo.com` + - Docs: `foo.com/docs` + - API Endpoint: `dash.foo.com/api/docs/user-info` -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**. - -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 +3. **Both on root domain** + - Dashboard: `foo.com/dashboard` + - Docs: `foo.com/docs` + - API Endpoint: `foo.com/api/docs/user-info` \ No newline at end of file diff --git a/advanced/widget/chat.mdx b/advanced/widget/chat.mdx index 216179a7..aa45248a 100644 --- a/advanced/widget/chat.mdx +++ b/advanced/widget/chat.mdx @@ -2,19 +2,18 @@ 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. +Add an AI-powered chat widget to your product that uses your docs as a knowledge base. ![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. Get your API key from 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) +### HTML Sites -## Installation - -Add the widget by adding these script tags into your site's `...` tag. +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 Apps + +Install and use the React 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 - -| Prop | Type | Description | -| --------------- | -------- | -------------------------------------------------------- | -| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. | -| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. | - -#### MintlifyWidgetDisplayChatProps - -| 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 `[]`. | +## Customization -### MintlifyWidgetTrackingFunctions +The widget supports customization for: +- Appearance (colors, dark mode) +- Display trigger (button or input field) +- Chat behavior +- Analytics tracking -| 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. | +[View full configuration options →](https://mintlify.com/docs/api-reference/widget) \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df3..0e2d784c 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. +Learn how to set up API documentation using MDX files and the `mint.json` configuration. - In your `mint.json` file, define your base URL and auth method: + In `mint.json`, set your base URL and authentication 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 API playground, add: ```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,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 `{}`: - + For path parameters, use `{}`: ```bash 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 `baseUrl` configured, 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 [here](/settings/navigation). - + \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 7d45da4f..a2c8166d 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -3,20 +3,17 @@ title: "OpenAPI Setup" description: "Reference OpenAPI endpoints in your docs pages" --- -## Add an OpenAPI specification file +## Getting Started with OpenAPI -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 use OpenAPI in your documentation, you need: +1. A valid OpenAPI 3.0+ specification file (JSON or YAML format) +2. Configuration in your `mint.json` -## Auto-populate API pages +## Auto-generate 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. +The simplest way to get started is by adding an `openapi` field to your `mint.json`: -**Example with Anchors:** - -```json {5} +```json { "anchors": [ { @@ -29,121 +26,45 @@ 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) - -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. +This automatically generates pages for each API endpoint with: +- Title from the OpenAPI operation summary +- Description from the OpenAPI operation description +- Version from your configuration (if specified) -* `version`: The `version` value from the anchor or tab, if present. +## Custom API Pages -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. +For more control over your API documentation, you can create custom MDX pages: -## Create MDX files for API pages +### Option 1: Auto-generate MDX Files -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 -``` - -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. +Generate MDX files for all endpoints using our scraper: ```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. - - +### Option 2: Create Manual MDX Files -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. +Create individual MDX files with OpenAPI references: -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 - --- - ``` - - -
+```md +--- +title: "Get users" +openapi: "GET /users" +--- +``` - 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. + If you have multiple OpenAPI files, include the full path: + `openapi: "/path/to/openapi.json GET /users"` -## 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: +## Schema Documentation - - ```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: "SchemaName" +--- +``` \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 57cd9368..ee2301dd 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -3,30 +3,28 @@ 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 +For help creating OpenAPI documents, we recommend these resources: +- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) - Learn OpenAPI syntax +- [Swagger's Editor](https://editor.swagger.io/) - See examples and test your specs +- [OpenAPI Validator](https://apitools.dev/swagger-parser/online/) - Debug your OpenAPI document - 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). + Most OpenAPI guides reference v3.0, which is largely compatible with v3.1. See the differences in [OpenAPI's migration guide](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). -## Specifying the URL for your API +## Essential 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 URLs +Define your API's base URL using the `servers` field. This is required for the API Playground to send requests. Multiple servers will show as a dropdown in the playground. Learn more about [server configuration](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. +### Authentication +Configure API authentication using `securitySchemes` and `security` fields. Common types include: +- Basic Authentication +- Bearer Tokens +- API Keys -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. +Check [Swagger's authentication guide](https://swagger.io/docs/specification/authentication/) for setup examples. -## 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. +Both server URLs and authentication can be overridden for specific endpoints if needed. \ No newline at end of file diff --git a/code.mdx b/code.mdx index b137fcce..6a95606a 100644 --- a/code.mdx +++ b/code.mdx @@ -4,36 +4,22 @@ description: "Display inline code and code blocks" icon: 'code' --- -## Basic +## Basic Usage ### 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 display `inline code`. ### 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 to create code blocks. Add a 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 advanced features and options, see the [Code Block documentation](/content/components/code). \ No newline at end of file diff --git a/content/components/accordion-groups.mdx b/content/components/accordion-groups.mdx index 29f90169..0733117a 100644 --- a/content/components/accordion-groups.mdx +++ b/content/components/accordion-groups.mdx @@ -4,12 +4,14 @@ description: "Group multiple accordions into a single display." icon: "table-rows" --- -Simply add `` around your existing `` components. +Wrap multiple `` components in an `` to display them as a unified set. - - You can put other components inside Accordions. + + Simply add `` around your existing `` components. + + ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { @@ -17,25 +19,22 @@ 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. + + For more accordion options, see the [Accordion](/content/components/accordions) docs. -````jsx Accordion Group Example +```jsx Accordion Group Example - - You can put other components inside Accordions. + + Simply add `` around your existing `` components. + + ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { @@ -43,19 +42,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. + + For more accordion options, see the [Accordion](/content/components/accordions) docs. -```` +``` -`AccordionGroup` does not have any props. +`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 d59351bb..d2d8f712 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -6,96 +6,53 @@ icon: "code" -````md Code Block Example -```javascript Code Block Example +```javascript Code Example const hello = "world"; ``` -```` ## Basic Code Block -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Create code blocks by wrapping your code with three backticks (```). ``` 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. +Add a language identifier after the backticks for syntax highlighting. We use [Prism](https://prismjs.com/#supported-languages) for highlighting. -```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!"); - } -} +```javascript +const greeting = "Hello, World!"; +console.log(greeting); ``` -```` - -## 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. +## Additional Features -```javascript Code Block Example -const hello = "world"; -``` +### Names +Add a title after the language identifier to name your code block: -````md Code Block Example -```javascript Code Block Example +```javascript My 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 `{line-numbers}` after the title: -```javascript Line Highlighting Example {1,3-5} +```javascript Example {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 - Read the reference for the Code Group component - + Learn how to display multiple code examples together + \ No newline at end of file diff --git a/content/components/mermaid-diagrams.mdx b/content/components/mermaid-diagrams.mdx index 1334bde5..741a04ee 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: -````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: +## What You Can Create -- Flowchart -- Sequence diagram -- Class diagram -- State diagram -- Entity relationship diagram -- User journey -- and more +Mermaid supports various types of diagrams: +- Flowcharts +- Sequence diagrams +- Class diagrams +- State diagrams +- Entity relationship diagrams +- User journeys +- And more -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). +For a complete list of diagrams, visit the [Mermaid website](https://mermaid.js.org/). -## Syntax for Mermaid diagrams +## Basic Usage -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. +To create a diagram, use the Mermaid code block syntax: ````md ```mermaid -// Your mermaid code block here +// Your mermaid code here ``` -```` +```` \ No newline at end of file diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe161..4b3b4348 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,27 +2,22 @@ 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. - -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. - -## How to Connect GA4 to Mintlify - -### Create a Web Stream + +If you're using Universal Analytics (UA), you'll need to create a new GA4 property. Both can coexist in the same Google Analytics project. + -You will need to create a web stream to get the Measurement ID to put into Mintlify. +## Setup Instructions -Click the cog at the bottom left of the Google Analytics screen. Then click on Data Streams. +### 1. Create a Web Stream +1. Open Google Analytics and click the settings cog at the bottom left +2. Navigate to Data Streams +3. Create a new Web Stream using 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. +### 2. Add Your Measurement ID -### Put Measurement ID in mint.json - -Add your Measurement ID to your `mint.json` file like so: +Copy your Measurement ID (`G-XXXXXXX`) from Stream Details and add it to your `mint.json`: ```json mint.json "analytics": { @@ -32,14 +27,8 @@ 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. +Data will appear in your Google Analytics dashboard within 2-3 days. You can verify the setup using the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en). - Preview links have analytics turned off. - - + \ No newline at end of file diff --git a/integrations/analytics/hotjar.mdx b/integrations/analytics/hotjar.mdx index a872a8f7..255600e2 100644 --- a/integrations/analytics/hotjar.mdx +++ b/integrations/analytics/hotjar.mdx @@ -1,8 +1,8 @@ --- -title: "HotJar" +title: "Hotjar" --- -Add the following to your `mint.json` file to send analytics to HotJar. +Configure Hotjar analytics by adding these options to your `mint.json`: ```json Analytics options in mint.json "analytics": { @@ -11,4 +11,4 @@ Add the following to your `mint.json` file to send analytics to HotJar. "hjsv": "required" } } -``` +``` \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index dff95d35..d80c5498 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -3,521 +3,42 @@ title: "Analytics Integrations" description: "Integrate with an analytics platform to track viewer events" --- +## Supported Platforms + - - - }> - - - - - - - - } -> - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> - + icon={}> + Track user events with Amplitude + + }> + Track page views with GA4 + -## Enabling Analytics - -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +## Quick Setup -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +Add your analytics keys to `mint.json` to enable tracking. You can add multiple platforms simultaneously. -```json Analytics options in mint.json -"analytics": { - "amplitude": { - "apiKey": "required" - }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, +```json mint.json +{ + "analytics": { "ga4": { - "measurementId": "required" - }, - "gtm": { - "tagId": "required" - }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" + "measurementId": "G-XXXXXXXX" }, - "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" + "amplitude": { + "apiKey": "your-api-key" } + } } ``` - \ No newline at end of file + + +See the individual platform pages for detailed setup instructions and available options. \ No newline at end of file diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d5..0c85f768 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 to your documentation, add the following to your `mint.json` file: -```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" + "osano": "https://cmp.osano.com/YOUR_SOURCE_URL/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 -