diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index f9d74b067..cfe35cbc5 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -2,31 +2,28 @@ title: Overview --- -## Trigger Updates - -Leverage the REST 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)! - ## 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 an API key through [the dashboard](https://dashboard.mintlify.com/settings/integrations). This key works across all deployments within your organization. +## Trigger Updates + +Use our REST API to programmatically trigger documentation updates. Additional API functionality will be added based on user feedback. Share your suggestions in [our community](https://mintlify.com/community). + ## Discovery API -The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing. -Responses include citations so you can point your users to the right places they need to get help. +The Discovery API enables AI-powered chat experiences within your documentation. Key features: +- Embedded chat interface for any application +- Responses include citations to source documentation +- Automatically stays synchronized with your content -## Getting Started +### Setup -To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget): +1. Generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget): - The Discovery API token is a public token that can be referenced in your - frontend code whereas the API key is a server-side token that should be kept - secret. + The Discovery API token is public and safe for frontend code. Keep the API key secure on your server side. -Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use -the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). +2. See our [example implementation](https://github.com/mintlify/discovery-api-example) or view the [live demo](https://chat.mintlify.com). \ No newline at end of file diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 13ff2d841..dc33fea4e 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -3,22 +3,20 @@ title: "Cloudflare" description: "Host documentation at a /docs subpath using Cloudflare Workers" --- -## Create Cloudflare Worker +## Quick 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` + - Give your worker a name and create it 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 Domain + - 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. +3. Add the Worker Script + - Click `Edit Code` + - Copy the script below + - Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values + - Click `Deploy` Cloudflare edit code - - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. - - ```javascript addEventListener("fetch", (event) => { event.respondWith(handleRequest(event.request)); @@ -52,9 +43,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]"; @@ -70,11 +59,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). +> Note: 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/widget/chat.mdx b/advanced/widget/chat.mdx index 5c1fc4756..3397d3835 100644 --- a/advanced/widget/chat.mdx +++ b/advanced/widget/chat.mdx @@ -9,15 +9,12 @@ description: "Integrate the Mintlify widget into your products to offer users qu ## 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). - - ![widget](https://mintlify-assets.b-cdn.net/widget/key.webp) - +2. Add the widget to your site: -## Installation - -Add the widget by adding these script tags into your site's `...` tag. +### HTML Installation +Add these scripts 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 Installation +For React and Next.js apps, use our 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 +## Configuration Options -| Prop | Type | Description | -| --------------- | -------- | -------------------------------------------------------- | -| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. | -| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. | +### Core Settings -#### MintlifyWidgetDisplayChatProps +| Prop | Description | +| ------------ | ---------------------------------------------------------- | +| `connection` | Required. Contains API connection details (`apiKey`) | +| `display` | Optional. Customize widget appearance and interactions | +| `tracking` | Optional. Add analytics tracking functions | -| Prop | Type | Description | -| ------------------------ | ---------- | ------------------------------------------------------------------ | -| `openCitationInSameTab?` | `boolean` | Open the citation url in the same tab or not. Defaults to `false`. | -| `exampleQueries?` | `string[]` | Example queries to prompt the user to ask. Defaults to `[]`. | +### Display Customization -### MintlifyWidgetTrackingFunctions +- **Trigger Types**: Choose between `button` or `input` display +- **Colors**: Customize `primary` and `primaryLight` colors +- **Dark Mode**: Toggle with `isDarkMode` +- **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 and examples, see our [advanced configuration guide]() + \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df30..9ba2f54f0 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -1,26 +1,26 @@ --- title: 'MDX Setup' -description: 'Generate docs pages for your API endpoints using MDX' +description: 'Configure API endpoints documentation using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Learn how to set up API documentation with MDX and generate an interactive API playground. - - 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 { @@ -31,13 +31,10 @@ 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). - - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + + Create an MDX file for each endpoint with the following metadata: ```md --- @@ -46,20 +43,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 paths with parameters, use `{parameterName}`: ```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` to display them in your sidebar. - + \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bc24fbbf6..c7f938efa 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -5,18 +5,19 @@ description: "Reference OpenAPI endpoints in your docs pages" ## Add an OpenAPI specification file -To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI -document in either JSON or YAML format that follows the -[OpenAPI specification](https://swagger.io/specification/). Your document must -follow OpenAPI specification 3.0+. +To get started, you 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 +To validate your OpenAPI spec, use: `mintlify openapi-check ` -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor. +## Add OpenAPI to Your Docs -**Example with Anchors:** +There are two main ways to include OpenAPI documentation: -```json {5} +### 1. Auto-populate API pages + +Add an `openapi` field to your `mint.json` to automatically generate pages for each OpenAPI operation. You can specify either a local path or URL to your OpenAPI document: + +```json { "anchors": [ { @@ -29,124 +30,43 @@ 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) - -To validate your OpenAPI spec, you can use this command:
`mintlify openapi-check ` - - -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 +### 2. Create Custom API Pages -For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper. +For more control over your API documentation, you can create individual MDX pages for each operation: -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. +#### Autogenerate MDX Files +Use our scraper to generate MDX files from your OpenAPI document: ```bash npx @mintlify/scraping@latest openapi-file -o api-reference ``` -Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). - -The scraper will output an array of -[Navigation entries](/settings/global#structure) containing your OpenAPI MDX -files. You can either append these entries to your existing Navigation, or -reorder and add the files to your navigation manually. - - - If your OpenAPI document is invalid, the files will not autogenerate. - - -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. +#### Manual Creation +Create MDX files manually by referencing OpenAPI operations in the page metadata: -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" +--- +``` -
+If you have multiple OpenAPI files, specify the path: +```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 what's specified in your OpenAPI document. -## 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: +You can also create pages for OpenAPI schemas defined in `components.schemas`: - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` - - ```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/changelog/overview.mdx b/changelog/overview.mdx index ad2c56f93..ec747fa47 100644 --- a/changelog/overview.mdx +++ b/changelog/overview.mdx @@ -1,346 +1 @@ ---- -title: "Product Updates" -description: "New updates and improvements" -mode: "center" ---- - - ## Authentication - - Authentication screenshot - - Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs. - - - - - - - - ## AI Assistant - - - AI Assistant - - - You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request. - - ## GitLab Integration Upgrade - - We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started. - - ## Web Editor - - - Web Editor - - - We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown. - - Check out our [docs on getting started with Web Editor](/web-editor). - - ## /llms.txt support - - - llms.txt support - - - All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org) - - ## Localization - - You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale. - - ### Quality Improvements - - * Return chat & search results based on the current version that the user is reading - - * Authenticate users with OAuth, in addition to JWT or Shared Session tokens. - - - - ## Changelogs - - Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users. - - - Changelog - - - ## Code Line Highlighting - - You can now highlight lines of code in your docs to emphasize and bring attention to important parts 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} - 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(); - ``` - ```` - - ## Light mode code blocks - - Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`: - - ```json - "codeBlock": { - "mode": "auto" - } - ``` - - ## Advanced Footer - - - Advanced Footer - - - You can now add more links to the standard footer. This upgrade - provides more consistency between landing pages and docs, or greater customization - if you want to spotlight specific pages like socials or status logs. - - ## Filter search based on the current user - - When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content. - - ## Custom Prompts for AI Chat - - You can now customize the prompts for the AI chat. Please reach out to [support](mailto:sales@mintlify.com) if you'd like to customize the prompts. - - ## Dashboard Improvements - - * Added ability to change custom domain to be /docs directly through dashboard settings. - - * Consolidated the login and signup pages to decrease friction and confusion. - - * Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them. - - * Added login with Google OAuth - - * Added ability to add new deployment through dashboard settings. - - ## Bug Fixes - - * Can now use leading slashes in navigation. - - * Can now edit CSS & JS files in the web editor. - - * Fixed `suggestEdit` not showing up even when enabled. - - * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results. - - * Don't allow search engines to crawl user-auth protected pages. - - * Revalidate the cache when an org is deleted. - - * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages. - - * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions. - - * Add in-line-style support for icons - - * Fixed the pop-in of custom CSS in docs. - - * Properly show in-line code styling in conjunction with links. - - * Maintain scroll position when you click the back button in a browser. - - - - ## Custom Fonts - - - Custom Fonts - - - Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand. - - ## Images in Card components - - Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](/content/components/cards#image-card). - - ## Update Speed Performances - - - Performance Improvements - - - For large projects (\~3,000 files), the download step for docs updates is now - \~440x faster - a 99.8% time reduction. Across the board, file downloads during - updates are now \~5.5x faster - an 81.8% time reduction. - - ## SEO improvements - - - SEO Improvements - - - We've fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements. - - ## Dashboard Improvements - - * App router migration in the dashboard. - - * Search analytics are now available in the dashboard. - - * Delete an org functionality has been added to the dashboard. - - * Shipped GitLab connection UI. - - * Fix incorrect analytics data. - - * Add-on's can now be directly purchased through the dashboard. - - ## Bug Fixes - - * Fixed a bug where the top bar would not stretch to the width of the screen when it's in custom mode and the sidebar layout is `sidenav`. - - * Fix relative positioning of the AI widget. - - ## More - - * **Troubleshooting for API pages**: API pages could be complicated so we listed - common issues to help you sort them out quickly — - [Read the docs](/api-playground/troubleshooting) - - - - ## OpenAPI Reference Pages - - * Endpoints defined by OpenAPI that are complex and recursive are now 98% - smaller. - - * We now show - [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/) - in OpenAPI pages. - - ## File Uploads in API Playground - - By default, API playground requests are proxied by Mintlify. Now you can use - `disableProxy` to disable this behavior and support request types like file - uploads. - - * [Learn more about API configurations](/settings/global#api-configurations) - - ## Mobile SEO improvements - - We've fixed the mobile layout of our docs so that they are more SEO-friendly - - including adding proper aria tags to elements. - - ## Support Form - - We added a more detailed support form to the Mintlify dashboard. You can now - submit a form to get in touch with us. - - ## Bug Fixes - - * Fixed a bug for the Segment integration functionality. - - * We now raise more granular error messages for GitHub permissions when - interacting with the editor. - - * Fixed bugs where the navigation would not properly expand when a direct link - was used. - - - - ## AI Widget - - - AI Widget - - - For `Pro` users, we introduced Mintlify Widget, an extension of your docs to - answer your users' questions when and where they asked. You can add this - AI-powered chatbot to any web page: your landing page, inside your product, or - on your existing documentation pages. - - * [Read the blog announcement](https://mintlify.com/blog/widget) - - * [Learn how to install the Widget](/advanced/widget/chat#getting-started) - - ## Pro Plan - - We also updated our pricing plans for better customizability and scale. - - * [Read the blog announcement](https://mintlify.com/blog/pro-plan) - - ## API Playground Code Example Sync - - When you browse API docs, the selected code example now syncs across your pages. - - ## Insights - - Currently in beta, this feature summarizes common user questions and patterns - into easy-to-digest reports with AI-powered suggestions on how to improve your - product. - - - - -## Launch Week Highlights -* Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling. -* Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated searchbar UI. -* Web Editor branching: create branches in our web editor without an IDE. -* User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers. -* OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json. - - - - - -## Okta SSO -We now support sign-on via Okta SAML and OIDC. - -## Mintlify REST API -Programmatically rigger updates to your documentation. - - - - - -## Custom mode -Add a configuration to the metadata to remove all elements except for the top bar. -Example use cases: -* Create a custom global landing page setup with custom components -* Add full-screen videos or image galleries -* Embed custom iFrame demo elements to add intractability to your docs - -Check out our [Custom Mode docs](/page#custom-mode). - - - - -## Mintlify MDX for VSCode -Call snippets of our pre-built components an dcallouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). - - - - - -## Quality Improvements -* Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments -* Versioning with tabs fully supported -* Wildcard redirects now supported -* CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development - - - - - -## Launch Week Highlights -* Preview Deployments: When you create a pull request, we'll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates. -* Snippets V2: We now support fully reusable components and variables for snippets. -* Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome. -* AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears. - - +null \ No newline at end of file diff --git a/content/components/code.mdx b/content/components/code.mdx index d59351bb4..9fc57dc31 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -6,96 +6,48 @@ icon: "code" -````md Code Block Example -```javascript Code Block Example +```javascript Code Example const hello = "world"; ``` -```` -## Basic Code Block +## Basic Usage -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Use three backticks (```) to create code blocks in your documentation: ``` 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 name after the backticks for syntax 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 +- **Names**: Add a title after the language name +```javascript My Example const hello = "world"; ``` -````md Code Block Example -```javascript Code Block Example -const hello = "world"; -``` -```` - -## Line Highlighting - -You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. - -```javascript Line Highlighting Example {1,3-5} +- **Line Highlighting**: Highlight specific lines using `{line-numbers}` +```javascript {2} const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); -} -sayHello(); +console.log(greeting); ``` -````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: +Need to show multiple code examples side by side? Check out our Code Groups: - Read the reference for the Code Group component - + Read about Code Groups + \ No newline at end of file diff --git a/content/components/mermaid-diagrams.mdx b/content/components/mermaid-diagrams.mdx index 1334bde52..a62d7c21a 100644 --- a/content/components/mermaid-diagrams.mdx +++ b/content/components/mermaid-diagrams.mdx @@ -4,33 +4,10 @@ description: 'Display diagrams using Mermaid' icon: 'diagram-project' --- - - -````md Mermaid Flowchart Example -```mermaid - flowchart LR - subgraph subgraph1 - direction TB - top1[top] --> bottom1[bottom] - end - subgraph subgraph2 - direction TB - top2[top] --> bottom2[bottom] - end - %% ^ These subgraphs are identical, except for the links to them: - - %% Link *to* subgraph1: subgraph1 direction is maintained - outside --> subgraph1 - %% Link *within* subgraph2: - %% subgraph2 inherits the direction of the top-level graph (LR) - outside ---> top2 -``` -```` - - - [Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. +## Example Diagram + ```mermaid flowchart LR subgraph subgraph1 @@ -41,16 +18,13 @@ 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 ``` -You can create the following using Mermaid diagrams: +## Available Diagram Types + +You can create various types of diagrams using Mermaid: - Flowchart - Sequence diagram @@ -62,12 +36,12 @@ You can create the following using Mermaid diagrams: For a complete list of diagrams supported by Mermaid, check out their [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 Mermaid diagram, use the following syntax: ````md ```mermaid -// Your mermaid code block here +// Your mermaid code here ``` -```` +```` \ No newline at end of file diff --git a/content/components/steps.mdx b/content/components/steps.mdx index 09700a488..a1e4f8de6 100644 --- a/content/components/steps.mdx +++ b/content/components/steps.mdx @@ -70,4 +70,4 @@ Steps are the best way to display a series of actions of events to your users. Y The size of the step titles. One of `p`, `h2` and `h3`. - + \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index fe9574b9b..b660ff897 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -3,591 +3,82 @@ title: "Analytics Integrations" description: "Integrate with an analytics platform to track events" --- -Automatically send data about your documentation engagement to your third party analytics provider. +Send data about your documentation engagement to your preferred analytics provider. -## All Integrations +## Available Integrations }> - + Industry-standard product analytics + - - - - - - } -> - - - - - - - - - } -> - - + - + - - + + - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> + }> + Most popular web analytics platform + - - - - - } -> + }> + Open-source analytics platform + - - - - - - - - } -/> + + View all supported integrations + ## Enabling Analytics -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +Add your analytics keys to `mint.json`. You can include multiple analytics platforms simultaneously. -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. - - - -```json Analytics options in mint.json -"analytics": { - "amplitude": { - "apiKey": "required" - }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, +```json +{ + "analytics": { "ga4": { - "measurementId": "required" - }, - "gtm": { - "tagId": "required" + "measurementId": "G-XXXXXXXX" }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" - }, - "mixpanel": { - "projectToken": "required" - }, - "pirsch": { - "id": "required" - }, - "plausible": { - "domain": "required" - }, - "posthog": { - "apiKey": "required", - "apiHost": "optional" + "amplitude": { + "apiKey": "YOUR_API_KEY" }, + // Add other platforms as needed + } } ``` -```json Google Analytics 4 Example -"analytics": { - "ga4": { - "measurementId": "G-XXXXXXX" - } -} -``` - - - -## FAQ + + View individual integration pages for platform-specific setup instructions. + - +## Tracked Events -- `expandable_open` -- `expandable_close` -- `accordion_open` -- `accordion_close` -- `header_nav_item_click` -- `cta_click` -- `scroll_to_bottom` -- `search_close` -- `api_playground_call` -- `search_result_click` -- `chat_enter` -- `chat_followup` -- `chat_completed` -- `code_block_copy` -- `chat_shared` -- `thumb_vote` -- `powered_by_mintlify_click` -- `ai_chat_citation_click` -- `ai_chat_feedback_positive_click` -- `ai_chat_feedback_negative_click` +Mintlify automatically tracks key user interactions including: - +- Content engagement (expanding/collapsing sections, scrolling) +- Navigation (header clicks, search usage) +- API playground usage +- Chat interactions +- Code block copying +- User feedback \ No newline at end of file diff --git a/integrations/analytics/posthog.mdx b/integrations/analytics/posthog.mdx index b78cabb18..c5d507702 100644 --- a/integrations/analytics/posthog.mdx +++ b/integrations/analytics/posthog.mdx @@ -2,37 +2,25 @@ 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 +```json mint.json "analytics": { "posthog": { "apiKey": "required", - "apiHost": "optional" - } -} -``` - -```json Example -"analytics": { - "posthog": { - "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW" + "apiHost": "optional" // Only needed for self-hosted PostHog } } ``` -
- - Enabling PostHog analytics will disable the analytics on the Mintlify dashboard. + Enabling PostHog analytics will disable the Mintlify dashboard analytics. ## Session Recordings -You need to add the URL for your docs website to Posthog's "Authorized domains for recordings" before you can receive session recordings. The option to add your URL is in Posthog's project settings. +To enable session recordings, add your docs website URL to PostHog's "Authorized domains for recordings" in your project settings. \ No newline at end of file diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d59..7a38e768e 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 the following in 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" -} -``` - -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 -