diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index 49b281047..96052f9fc 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -6,17 +6,13 @@ title: Introduction The Mintlify REST API is only available on the startup plan and above. -Leverage the external API to programmatically trigger an update when desired. -The primary use-case will be to trigger updates. We will be adding more and more -functionality to the API overtime. Let us know what else you want to see in -[our community](https://mintlify.com/community)! +The Mintlify REST API allows you to programmatically trigger documentation updates. For feature requests, join us in [our community](https://mintlify.com/community). ## Authentication -You can generate an API key through -[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is -associated with the entire org and can be used across multiple deployments. +Generate your API key in [the dashboard](https://dashboard.mintlify.com/settings/integrations). Each API key works for all deployments within your organization. + \ No newline at end of file diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 763b44eda..3b0c1809f 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -7,22 +7,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; -## Create Cloudflare Worker +## Setup Guide -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 Worker + - Go to `Workers & Pages > Create application > Create worker` + - Create a new Cloudflare 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. Configure Domain + - In your worker, go to `Settings > Triggers` + - Click `Add Custom Domain` + - Add your domain (both with and without `www.`) -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 Worker Script + - Click `Edit Code` + - Copy and paste the script below + - Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values + - Click `Deploy` ```javascript addEventListener("fetch", (event) => { @@ -80,5 +67,4 @@ async function handleRequest(request) { } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +Note: Changes may take a few hours to propagate. For setup assistance, [contact our support team](mailto:sales@mintlify.com). \ No newline at end of file diff --git a/advanced/subpath/vercel.mdx b/advanced/subpath/vercel.mdx index 925561f9f..eed73aa41 100644 --- a/advanced/subpath/vercel.mdx +++ b/advanced/subpath/vercel.mdx @@ -3,14 +3,7 @@ title: "Vercel" description: "Host documentation at a /docs subpath using Vercel" --- -import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; - - - -## vercel.json Configuration - -To host your documentation at a custom subpath using Vercel, you need to add the -following configuration to your `vercel.json` file. +To host your documentation at a custom subpath using Vercel, add the following configuration to your `vercel.json` file: ```json { @@ -28,7 +21,5 @@ following configuration to your `vercel.json` file. ``` - For more information, you can also refer to Vercel's offical guide on - rewrites: [Project Configuration: - Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) - + For more information, see [Vercel's rewrites documentation](https://vercel.com/docs/projects/project-configuration#rewrites) + \ No newline at end of file diff --git a/advanced/widget/chat.mdx b/advanced/widget/chat.mdx index 216179a7a..844399bc9 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. +Integrate the Mintlify chat widget into your products to provide AI-powered documentation search for your users. ![widget](https://mintlify-assets.b-cdn.net/widget/hero.webp) ## Getting started -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 using one of the following methods: -![widget](https://mintlify-assets.b-cdn.net/widget/key.webp) +### HTML Installation -## 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 Installation + +Install and use the `@mintlify/widget-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 +## Configuration -| 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 `[]`. | +The widget can be customized using the following main properties: -### MintlifyWidgetTrackingFunctions +| Prop | Description | +|------|-------------| +| `connection.apiKey` | Required. Your widget API key | +| `display.trigger.type` | Optional. Either 'button' or 'input' | +| `display.trigger.label` | Optional. Custom trigger text | +| `display.colors.primary` | Optional. Custom primary color | +| `display.chat.exampleQueries` | Optional. Array of example questions | -| 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 advanced configuration options, visit our [detailed configuration guide]() + \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 7d45da4f6..88dfef742 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -3,147 +3,57 @@ title: "OpenAPI Setup" description: "Reference OpenAPI endpoints in your docs pages" --- -## Add an OpenAPI specification file +## Add an 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+. +Ensure you have a valid OpenAPI document (v3.0+) in JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). -## Auto-populate API pages +## Configure Your 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. +There are two ways to add OpenAPI documentation: -**Example with Anchors:** +### 1. Auto-populate (Recommended) -```json {5} +Add an `openapi` field to your `mint.json` to automatically generate API pages: + +```json { "anchors": [ { "name": "API Reference", "openapi": "/path/to/openapi.json", - "url": "api-reference", - "icon": "square-terminal" - } - ] -} -``` - -![](/images/anchors-autogeneration-anchors.png) - -**Example with Tabs:** - -```json {6} -{ - "tabs": [ - { - "name": "API Reference", - "url": "api-reference", - "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" + "url": "api-reference" } ] } ``` -![](/images/autogeneration-with-tabs.png) +### 2. Create Custom MDX Pages -When using this option, the metadata for the generated pages will have the following default values: - -* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. - -* `description`: The `description` field from the OpenAPI operation, if present. - -* `version`: The `version` value from the anchor or tab, if present. - -There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page. - -## Create MDX files for API pages - -If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). - -![](/images/elevenlabs-mdx-autogeneration-example.png) - -### Autogenerate files - -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. +For more customization, create individual MDX pages for each API endpoint: +1. **Auto-generate pages** (recommended for large APIs): ```bash npx @mintlify/scraping@latest openapi-file -o api-reference ``` -Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). - -The scraper will output an array of -[Navigation entries](/settings/global#structure) containing your OpenAPI MDX -files. You can either append these entries to your existing Navigation, or -reorder and add the files to your navigation manually. - - - If your OpenAPI document is invalid, the files will not autogenerate. - - -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. - -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 - --- - ``` - - -
+2. **Manual creation**: +```md +--- +title: "Get users" +openapi: "/path/to/openapi.json 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. + The method and path must exactly match your OpenAPI document specification. -## 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: +## OpenAPI Schemas - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` +To create pages for OpenAPI schemas: - ```md Format - --- - openapi-schema: "schema-key" - --- - ``` - \ No newline at end of file +```md +--- +openapi-schema: "schema-name" +--- +``` \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 57cd93680..9d893de43 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -3,30 +3,22 @@ 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 write effective OpenAPI documentation, you can use these helpful resources: +- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) - Learn OpenAPI syntax +- [Swagger's Editor](https://editor.swagger.io/) - Try out examples +- [Swagger & 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). - +## Key Components -## Specifying the URL for your API +### Base URL Configuration +Use the `servers` field to specify your API's base URL. This is required for the API Playground to work properly. Multiple servers can be specified to allow switching between environments. -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/). +### Authentication +Define your API's authentication methods using the `securitySchemes` field. Common types include: +- Basic Authentication +- Bearer Authentication +- API Keys -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. - -If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation. - -## Specifying authentication - -Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. - -The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. - -If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. +Apply authentication to your endpoints using the `security` field. Find detailed examples in [Swagger's authentication guide](https://swagger.io/docs/specification/authentication/). \ No newline at end of file diff --git a/code.mdx b/code.mdx index b137fcce0..a5d443673 100644 --- a/code.mdx +++ b/code.mdx @@ -4,36 +4,20 @@ description: "Display inline code and code blocks" icon: 'code' --- -## Basic +## Using Code ### 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 mark `inline code`. ### Code Block +Create code blocks using three backticks with an optional language name for syntax highlighting: -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java +```java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` -```` -Visit the [Code Block page](/content/components/code) for more detailed docs. +For advanced features, 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..280af2126 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!"); - } - } - ``` - + + You can put any content inside Accordions. - - 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. + + You can put any content inside Accordions. - + Check out the [Accordion](/content/components/accordions) docs for all the supported props. -```` +``` -`AccordionGroup` does not have any props. +`AccordionGroup` does not have any props. \ No newline at end of file diff --git a/development.mdx b/development.mdx index 15581014c..812d63091 100644 --- a/development.mdx +++ b/development.mdx @@ -4,99 +4,66 @@ 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. Start the development server: ```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 +### Using a Different Port ```bash -mintlify dev --port 3333 +mintlify dev --port ``` -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: - +### Updating Mintlify - - ```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: - +### Checking 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. +## Recommended Tools +- [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) - For syntax highlighting +- [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 the ~/.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..92ce593ec 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,28 +2,21 @@ 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. +Connect your Mintlify documentation to GA4 to track visitor analytics. -If you are using the old version of Google Analytics, Universal Analytics, you will still be able to generate a GA4 property. GA4 data is slightly different from UA data but still gets collected in the same project. +## Setup Steps -## How to Connect GA4 to Mintlify +1. Create a GA4 property if you haven't already (works alongside existing Universal Analytics properties) -### 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. +2. Create a Web Stream + - Go to Settings (cog icon) → Data Streams + - Click "Add Stream" → Web + - Enter your Mintlify docs URL + - Copy your 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: - +3. Add to mint.json: ```json mint.json "analytics": { "ga4": { @@ -32,14 +25,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. - - - -Preview links have analytics turned off. +## Verification - +- Data takes 2-3 days to appear in Google Analytics +- Use [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to verify setup +- Analytics are disabled on preview links diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index dff95d35a..349b4486a 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -3,6 +3,12 @@ title: "Analytics Integrations" description: "Integrate with an analytics platform to track viewer events" --- +# Analytics Integrations + +Mintlify supports integration with popular analytics platforms to help you track and understand how users interact with your documentation. + +## Available Platforms + - + }> - - - - - - - - } -> + - - - - - - - - } -> - - - - - - - + + + + + + + - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> + + } + /> - - - - - - } -> + + + + + + } + /> - - - - - - + - - - + + + + - - - - - - + + - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> - -## Enabling Analytics - -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +## Setup Guide -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +Enable analytics by adding your platform's credentials to `mint.json`. You can add multiple analytics platforms: - - -```json Analytics options in mint.json -"analytics": { - "amplitude": { - "apiKey": "required" - }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, +```json +{ + "analytics": { "ga4": { - "measurementId": "required" - }, - "gtm": { - "tagId": "required" - }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" + "measurementId": "G-XXXXXXX" }, "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": "XXXXXXX" } + } } ``` - \ No newline at end of file +See each platform's dedicated page for specific configuration details. \ No newline at end of file diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d59..606273440 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, include your Osano source URL in `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" + "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 -