diff --git a/.gitignore b/.gitignore index b67b2bc7a3..4170138cf6 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ node_modules package-lock.json .idea/ .vscode/ +.pr-body.md diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index f0c09dcbfd..341f378d8b 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -5,11 +5,14 @@ ACS Adobe AEO agentic +AGENTS Ahrefs AI +allOf allowlists? AllViewerExceptHostHeader Anthropic +anyOf API apiHost apiKey @@ -30,6 +33,7 @@ autofocus(es)? automations? (?i)automerge (?i)autoplay +autosave(s|d)? autoupdate AVIF await @@ -52,8 +56,9 @@ CAA CachingDisabled CachingEnabled CachingOptimized -(?i)captchas? +Caddy callouts? +(?i)captchas? camelCase Cascade CD @@ -96,6 +101,7 @@ ctx Cursor cURL customizability +Datadog debounce[ds]? (?i)deduplic(ated?|ation) desc @@ -107,6 +113,7 @@ dir Di(?:á|a)taxis Discord discoverability +discoverable dismissible Django DMs? @@ -159,9 +166,11 @@ GitHub GitLab Golang GraphQL +gRPC Grok GTM gui +hardcod(e[ds]?|ing) hCaptcha headless (?i)heatmaps? @@ -180,6 +189,7 @@ HubSpot ICO IDE IdP +idempoten(t|cy|ce) IDs iframes? Imgix @@ -235,7 +245,7 @@ macOS md MDX measurementId -(?i)Memoize +(?i)memoiz(e[ds]?|ation) Mermaid (?i)metadata metatags? @@ -254,11 +264,13 @@ mvc myName myObject MySQL +namespaces? nav (?i)navbar Next.js nginx n8n +Nango Node.js (?i)noindex nondeterministic @@ -344,6 +356,7 @@ req res REST resubmit +reupload(s|ed|ing)? revalidat(es?|ion) ROI Ronan @@ -356,6 +369,7 @@ rulesets? runtime Rust SaaS +Salesforce SAML sanitization Scala @@ -366,11 +380,13 @@ scrollbar scss SDK SDKs +searchable SendSafely SEO serverless sessionRecording setup +shard(s|ing)? Shiki shortcodes? sidebars? @@ -446,6 +462,7 @@ UIs (?i)unauthenticated uncached uncategorized +(?i)uncheck(s|ed|ing)? unclickable undefined ungroup(s|ed|ing)? diff --git a/admin-openapi.json b/admin-openapi.json index efbd482520..c433d51487 100644 --- a/admin-openapi.json +++ b/admin-openapi.json @@ -29,7 +29,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." } ], "requestBody": { @@ -126,7 +126,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "id", @@ -237,7 +237,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "skip", @@ -370,7 +370,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." } ], "requestBody": { @@ -437,7 +437,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "id", @@ -485,7 +485,7 @@ "schema": { "type": "string" }, - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "id", @@ -627,7 +627,7 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard." } } } diff --git a/agent/effective-prompts.mdx b/agent/effective-prompts.mdx index 2bd9ae82ee..05986c5fd8 100644 --- a/agent/effective-prompts.mdx +++ b/agent/effective-prompts.mdx @@ -26,7 +26,7 @@ Use broad prompts for general content maintenance like fixing typos, updating re If you have multiple documentation sites, include the `subdomain` parameter in your message to specify which documentation set the agent should work on. -To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`. +To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is `https://app.mintlify.com/org-name/domain-name`, your domain name is `domain-name`. Use the format `@mintlify subdomain= ` to prompt the agent to work on a specific documentation set. diff --git a/agent/index.mdx b/agent/index.mdx index 179be5d8f5..43d881df0f 100644 --- a/agent/index.mdx +++ b/agent/index.mdx @@ -6,10 +6,6 @@ keywords: ["automation", "automate", "AI", "autoupdate", "maintenance"] import SkillMcpPrompt from "/snippets/skill-mcp-prompt.mdx"; - - The agent is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent). - - The agent is an AI tool that creates pull requests with proposed changes to your documentation based on your prompts. When you send a request, the agent: - **Researches**: Searches and reads your existing documentation, any connected repositories, relevant context, and the web. @@ -29,6 +25,7 @@ Use the agent to: - Process and include images, diagrams, and other files from Slack attachments. - Search and revise code examples and API references across your docs. - Reference source code from any repository that has the Mintlify GitHub App installed. +- Pull live context from connected apps like Slack, Notion, Linear, and Jira. - Automate documentation maintenance with workflows. - Answer questions about your docs and technical writing topics. - Address code review feedback to maintain documentation quality. @@ -37,7 +34,7 @@ Use the agent to: ## Connect your GitHub account -By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://dashboard.mintlify.com/settings/account) page of the dashboard. +By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://app.mintlify.com/settings/account) page of the dashboard. ## Connect repositories as context @@ -56,8 +53,8 @@ To let an external agent edit your content directly through MCP tool calls, conn Add the agent to your Slack workspace. - -Give the agent access to your Notion workspace. + +Give the agent access to Slack, Notion, Linear, and other tools. Configure the agent with an `AGENTS.md` file. diff --git a/agent/integrations.mdx b/agent/integrations.mdx new file mode 100644 index 0000000000..9cf48d3057 --- /dev/null +++ b/agent/integrations.mdx @@ -0,0 +1,50 @@ +--- +title: "Agent integrations" +description: "Connect third-party apps so the agent can pull live context from Slack, Notion, Linear, Jira, and other tools when answering questions and updating content." +keywords: ["integrations", "Slack", "Notion", "Linear", "Jira", "Salesforce", "Intercom", "Google Calendar", "context", "Nango"] +--- + +Agent integrations give the agent access to context from other tools that your team uses. Once connected, the agent can search Slack threads, read Notion pages, look up Linear issues, and pull context from other apps to inform its responses and content updates. + +## Connect an integration + +Admins and editors can connect an integration for their organization from the dashboard. + +1. Go to the [Agent integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard. +2. Find the integration you want to connect. +3. Click **Connect**. +4. Follow the OAuth prompts to authorize Mintlify to access your account. + +Some integrations, like Jira and Salesforce, open an additional configuration step to enter your workspace URL or subdomain before the OAuth flow begins. + +Once connected, everyone in your organization can prompt the agent to use the integration in Slack or for workflows that support integrations. + +## Supported integrations + +- Google Calendar +- Intercom +- Jira +- Linear +- Notion +- Salesforce +- Slack + +## How the agent uses integrations + +The agent uses connected integrations as tools. When you ask the agent a question or give it a task, it can search and retrieve content from your connected apps to build context. + +For example: +- "Summarize the Slack thread about the v2 API migration and write it up for the knowledge base." +- "Check the Linear ticket for this feature and document the behavior." +- "What did the team decide about rate limiting? Check Slack." + +The agent only accesses integration data when it's relevant to the request. It does not proactively read from connected apps. + +## Disconnect an integration + +1. Go to the [Agent integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard. +2. Find the connected integration you want to disconnect. +3. Click **Configure**. +4. Click **Disconnect**. + +Disconnecting removes the integration for your organization. The agent immediately loses access to that tool. diff --git a/agent/notion.mdx b/agent/notion.mdx deleted file mode 100644 index 569cbc0852..0000000000 --- a/agent/notion.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Connect Notion to the agent" -description: "Connect Notion to the Mintlify agent so it can reference your workspace pages and databases as context when creating documentation updates." -keywords: ["Notion", "integration", "knowledge base", "context"] ---- - -Connect your Notion workspace to the agent so that it can search your Notion content and use it as context when creating documentation updates. The additional context from your team's knowledge base, product specs, and internal documentation stored in Notion helps the agent create more accurate and complete documentation. - -## Connect your Notion workspace - -1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard. -2. In the "Agent settings" section, click **Install Notion app**. - - The App settings section with the Slack and Notion install buttons. - The App settings section with the Slack and Notion install buttons. - -3. Follow the prompts to authorize Mintlify to access your Notion workspace. -4. In Notion's authorization screen, select which pages and databases to share with Mintlify. - -## What the agent can do with Notion - -The Notion integration uses Notion's [MCP tools](https://developers.notion.com/guides/mcp/mcp-supported-tools#mcp-tools) to search and read your workspace content. - -Your content in Notion becomes additional context for the agent to use when generating documentation. - -When the agent has access to your Notion workspace, it can: - -- **Search Notion**: Find relevant pages and databases in your connected Notion workspace based on the context of your request. -- **Read Notion pages**: Access the content of Notion pages to use as reference material when generating documentation. -- **Reference databases**: Pull structured data from Notion databases to inform documentation updates. - -## Use cases - -- **Sync product specs to docs**: Reference product requirement documents and design specs stored in Notion when writing feature documentation. -- **Document from meeting notes**: Point the agent to meeting notes or decision logs in Notion to draft documentation based on team discussions. -- **Pull from internal knowledge bases**: Use internal wikis and knowledge bases in Notion as source material for public-facing documentation. - -## Best practices - -- **Scope access carefully**: Only grant access to the Notion pages and databases that contain information relevant to your documentation. -- **Provide specific references**: When prompting the agent, mention the specific Notion page or database you want it to reference for best results. -- **Review generated content**: Always review pull requests to ensure information from Notion is appropriately adapted for your public documentation. diff --git a/agent/slack.mdx b/agent/slack.mdx index 9d8f50ba5e..12f41f8658 100644 --- a/agent/slack.mdx +++ b/agent/slack.mdx @@ -1,6 +1,6 @@ --- title: "Add the agent to Slack" -description: "Add the Mintlify agent to Slack to ask questions about your docs, create documentation updates from conversations, and capture team knowledge." +description: "Install the Mintlify agent in Slack to ask questions about your product, create content updates from team conversations, and capture knowledge in pull requests." keywords: ["Slack integration", "Slack bot", "team collaboration", "agent integration", "knowledge capture"] --- @@ -8,20 +8,44 @@ keywords: ["Slack integration", "Slack bot", "team collaboration", "agent integr If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it. +Use the agent in Slack to update your content, ask questions, and capture team knowledge. Mention the agent in a channel to use it collaboratively, or send it a direct message to use it privately. + + + This page covers adding the agent as a bot to your Slack workspace. To give the agent access to Slack channel content as a data source, see [Agent integrations](/agent/integrations). + + ## Connect your Slack workspace -1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard. +1. Go to the [Agent](https://app.mintlify.com/products/agent) page in your dashboard. 2. In the "Agent settings" section, click **Install Slack app**. The App settings section with the Slack and Notion install buttons. The App settings section with the Slack and Notion install buttons. -3. Follow the Slack prompts to install the `mintlify` app in your workspace. -4. Follow the Slack prompts to link your Mintlify account to your Slack workspace. +3. Follow the Slack prompts to install the `mintlify` app in your workspace and grant the requested permissions. +4. Confirm the connection in your Mintlify dashboard to your Slack workspace. 5. Test that the agent is working and responds when you: - Send a direct message to the agent. - Mention the agent with `@mintlify` in a channel. + + Each Slack workspace can connect to only one Mintlify organization at a time. If you try to install the agent into a workspace that is already connected to a different organization, the installation fails with a "wrong organization" error. Uninstall the app from the other organization first, or use a different Slack workspace. + + You can install the Slack agent even if you don't have a Mintlify-hosted deployment. The agent still works for question answering and conversations. Features that open pull requests require a connected repository. + + + + On Slack Enterprise Grid, installing the app to your organization is not enough. You must also install it to the specific workspace where you want to use the agent. If you skip this step, the agent appears available at the org level but does not respond in your workspace. + + To add the app to a workspace, open your org's app management page at a URL like `https://app.slack.com/manage//integrations/installed`, find the `mintlify` app, and install it to your workspace. + + +### Reconnect or reinstall the agent + +If you must reauthorize the agent—for example, to grant new permissions after a Slack scope update or to recover from a revoked token—reinstall the app from your Mintlify dashboard. + +When you reinstall the agent into a workspace that is already connected to your organization, Mintlify refreshes the stored bot token in place. Your existing channels, threads, and per-user integrations remain intact. + If your organization has multiple deployments, the agent asks you to choose which deployment to work with the first time you send a request. @@ -32,26 +56,6 @@ message in the thread. The agent retains your conversation history so you can continue where you left off with the new deployment. -## Connect additional integrations from Slack - -Once your Slack workspace is connected, you can ask the agent in Slack to set up any third-party integration that it should use as context. The agent uses [Composio](https://docs.composio.dev/toolkits) to support a broad catalog of third-party services, including issue trackers, knowledge bases, CRMs, and developer tools. - -To add a new integration from Slack: - -1. In a direct message or a thread that mentions `@mintlify`, ask the agent to set up the integration. For example: - - "Set up the GitHub integration." - - "Connect Jira so you can read tickets." - - "Install the HubSpot integration." -2. The agent replies with an authorization link. -3. Click the link, sign in to the third-party service, and approve the requested permissions. -4. Return to Slack. The agent confirms the connection and can immediately use the integration as context for future requests. - -Integrations that you connect from Slack are scoped to individual Slack users, so each teammate sets up their own connections and the agent uses the connections of whoever sent the message. If a Slack user has not connected a service, the agent falls back to the organization-level integrations installed from the [Agent](https://dashboard.mintlify.com/products/agent) page in the dashboard. - -To remove or reauthorize an organization-level integration, use the **Agent settings** section of the [Agent](https://dashboard.mintlify.com/products/agent) page. - -For the full list of supported services, see the [Composio toolkits catalog](https://docs.composio.dev/toolkits). - ## Use the agent in Slack Once connected, you can: @@ -59,7 +63,7 @@ Once connected, you can: - Send direct messages to the agent to use it privately. - Mention `@mintlify` in a channel to use it publicly and collaboratively. - Attach files and images directly to your messages for the agent to process and include in your docs. -- Continue conversations in threads to iterate on changes or ask follow-up questions. +- Continue conversations in threads to iterate on changes or ask follow-up questions. The agent reuses files, images, and emoji reactions from earlier in the thread as context for follow-up requests, so you don't have to reupload them. - Share pull request links with the agent to update related documentation. ## Ask questions about your docs @@ -80,13 +84,13 @@ Use the agent to update your documentation with a new request or in an existing - **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update. - **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update. -- **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation. +- **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation. In a thread, the agent has access to images and files shared in earlier messages, so you can reference them in follow-up requests without reuploading. The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates. ## Reference other repositories -The agent can read source code from any repository that has the Mintlify GitHub App installed, even if it isn't your documentation repository. This lets the agent build deeper context to guide documentation updates. +The agent can read source code from any repository connected through the [GitHub app](/deploy/github) or [GitLab integration](/deploy/gitlab), even if it isn't your documentation repository. This lets the agent build deeper context to guide documentation updates. When you mention another repository in your request, the agent clones it on demand and inspects the relevant files before drafting changes. @@ -96,7 +100,7 @@ Example prompts: - "Document the new endpoints added in `acme/backend#1234`." - "What repositories do you have access to?" -Cloned repositories are read-only. The agent uses them for context, but always opens pull requests against your documentation repository. +The agent treats cloned repositories as read-only. It uses them for context, but always opens pull requests against your documentation repository. ## Track progress in real time @@ -105,9 +109,19 @@ When the agent is making changes to your documentation, it provides live feedbac - **Status updates**: A live-updating message shows what the agent is doing, such as how many files it has searched, read, and edited. - **Task progress**: When the agent breaks your request into multiple tasks, it displays a checklist so you can track progress on each one. - **Questions**: If the agent needs more information, it presents options for you to select from or reply in the thread with a custom answer. +- **Permission requests**: Before the agent runs a third-party action that writes data, such as sending an email or creating a ticket, it asks you to approve or deny the action. The permission request is only visible to the person who triggered the request. Click **Approve** to let the agent proceed or **Deny** to cancel the action. - **Interruptions**: If you send a follow-up message while the agent is still working, it stops the current task and starts on the new one. - **Completion**: When the agent finishes, it posts a summary with a link to the pull request and a link to open the changes in the web editor. +## Roles and permissions + +The agent's capabilities in Slack match users' [roles](/dashboard/roles). + +- **Admins and editors**: Can ask questions and make documentation changes. The agent has access to file editing and pull request tools. +- **Viewers**: Can ask questions only. The agent runs in read-only mode for Mintlify tools and third-party integrations. + +To change a teammate's permissions, update their role on the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. + ## Best practices - **Be specific**: Tell the agent exactly what you want to know or what you want changed and where. diff --git a/agent/use-cases.mdx b/agent/use-cases.mdx index 5a96255725..7a000369d2 100644 --- a/agent/use-cases.mdx +++ b/agent/use-cases.mdx @@ -64,7 +64,7 @@ For example: `@mintlify Users are getting confused by step 3 in the setup guide. Create workflows to automate recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product. -See [Workflows](/workflows/index) for more information. +See [Workflows overview](/workflows/index) for more information. ## Automate with the API @@ -73,5 +73,3 @@ Integrate the agent into your existing automation tools to automatically update Use the agent endpoints to [create jobs](/api/agent/v2/create-agent-job), [get job status](/api/agent/v2/get-agent-job), and [send messages](/api/agent/v2/send-message). When creating jobs via the API, you can control whether pull requests open in draft mode using the `asDraft` parameter (defaults to `false`). Set `asDraft: true` to create draft pull requests, or keep the default to create non-draft pull requests ready for immediate review and merging in automated workflows. - -Learn how to set up API automation in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial. diff --git a/ai/contextual-menu.mdx b/ai/contextual-menu.mdx index f888e98c83..996e1190ba 100644 --- a/ai/contextual-menu.mdx +++ b/ai/contextual-menu.mdx @@ -1,13 +1,13 @@ --- title: "Contextual menu" description: "Add a contextual menu to your docs with one-click AI integrations for ChatGPT, Claude, Perplexity, Google AI Studio, Devin, Windsurf, and MCP tools." -keywords: ["AI tools", "ChatGPT", "Claude", "Perplexity", "MCP", "Grok", "cursor", "vscode", "vs code", "Google AI Studio", "aistudio", "Devin", "Windsurf"] +keywords: ["AI tools", "ChatGPT", "Claude", "Perplexity", "MCP", "Grok", "cursor", "vscode", "vs code", "Google AI Studio", "aistudio", "Devin", "Windsurf", "pdf"] --- import { PreviewButton } from "/snippets/previewbutton.jsx" import IconsRequired from "/snippets/icons-required.mdx"; -The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users select the contextual menu on any page, they can copy content as context for AI tools or open conversations in ChatGPT, Claude, Perplexity, Google AI Studio, Grok, Devin, Windsurf, or a custom tool of your choice with your documentation already loaded as context. +The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users click the contextual menu on any page, they can copy content as context for AI tools or open it in an AI conversation. Supported tools include ChatGPT, Claude, Perplexity, Google AI Studio, Grok, Devin, Windsurf, and any custom tool you configure. Pair the contextual menu with your hosted [`skill.md`](/ai/skillmd) file and [MCP server](/ai/model-context-protocol) so that users can install your product's full capabilities into their AI tools, not just the page they are reading. @@ -22,6 +22,7 @@ The contextual menu includes several pre-built options that you can enable by ad | **Copy page** | `copy` | Copies the current page as Markdown for pasting as context into AI tools | | **View as Markdown** | `view` | Opens the current page as Markdown | | **Ask assistant** | `assistant` | Opens the [assistant](/assistant/index) with the current page as context | +| **Download PDF** | `download-pdf` | Downloads the current page as a PDF. Available on [Enterprise plans](https://mintlify.com/pricing). | | **Open in ChatGPT** | `chatgpt` | Creates a ChatGPT conversation with the current page as context | | **Open in Claude** | `claude` | Creates a Claude conversation with the current page as context | | **Open in Perplexity** | `perplexity` | Creates a Perplexity conversation with the current page as context | @@ -34,6 +35,8 @@ The contextual menu includes several pre-built options that you can enable by ad | **Connect to Cursor** | `cursor` | Installs your hosted MCP server in Cursor | | **Connect to VS Code** | `vscode` | Installs your hosted MCP server in VS Code | | **Connect to Devin** | `devin-mcp` | Installs your hosted MCP server in Devin | +| **Download API spec** | `download-spec` | Downloads your deployment's OpenAPI spec. If there are multiple specs, downloads them as a zip archive. Only appears on API reference pages. | +| **Download PDF** | `download-pdf` | Downloads the current page as a PDF | | **Custom options** | Object | Add custom options to the contextual menu | @@ -43,7 +46,7 @@ The contextual menu includes several pre-built options that you can enable by ad /> -## Enabling the contextual menu +## Enable the contextual menu Add the `contextual` field to your `docs.json` file and specify which options you want to include. @@ -64,7 +67,9 @@ Add the `contextual` field to your `docs.json` file and specify which options yo "mcp", "cursor", "vscode", - "devin-mcp" + "devin-mcp", + "download-spec", + "download-pdf" ] } } @@ -88,7 +93,7 @@ By default, the contextual menu appears in the page header. You can configure it | `header` | Displays options in the top-of-page context menu (default) | | `toc` | Displays options in the table of contents sidebar | -## Adding custom options +## Add custom options Create custom options in the contextual menu by adding an object to the `options` array. Each custom option requires these properties: diff --git a/ai/llmstxt.mdx b/ai/llmstxt.mdx index 9d29fb2b96..0df6e300b1 100644 --- a/ai/llmstxt.mdx +++ b/ai/llmstxt.mdx @@ -2,6 +2,7 @@ title: "llms.txt" description: "Automatically generate llms.txt and llms-full.txt files so AI tools like ChatGPT and Claude can index and understand your documentation." keywords: ["llms.txt", "LLM indexing", "AEO", "GEO", "content discovery"] +boost: 3 --- import { PreviewButton } from "/snippets/previewbutton.jsx" @@ -11,7 +12,10 @@ The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs Mintlify automatically hosts an `llms.txt` file at the root of your project that lists all available pages in your documentation. This file is always up to date and requires zero maintenance. You can optionally add a custom `llms.txt` file to the root of your project. - If your site requires authentication, `llms.txt` and `llms-full.txt` also require authentication to view. LLMs and AI tools that cannot authenticate into your site cannot access these files. The files exclude pages that belong to [user groups](/deploy/authentication-setup#control-access-with-groups). + Authentication affects `llms.txt` and `llms-full.txt` differently depending on your site configuration: + + - **Fully authenticated sites**: Both files require authentication. AI tools that cannot authenticate cannot access them. + - **Partially authenticated sites**: Both files are publicly accessible, but only list public pages. Pages restricted to user groups are excluded. For more information on how authentication affects AI features, see [Feature availability](/deploy/authentication-setup#feature-availability). diff --git a/ai/markdown-export.mdx b/ai/markdown-export.mdx index 7d284da7b1..2e2206b8a2 100644 --- a/ai/markdown-export.mdx +++ b/ai/markdown-export.mdx @@ -60,6 +60,16 @@ Agents submit feedback by posting to the endpoint with the page path and feedbac Use agent feedback to improve your pages for agents based on what they find incorrect, outdated, or confusing. +## Authentication + +Markdown export respects the same authentication rules as the HTML version of each page. + +| Authentication mode | Behavior | +|-----------|----------| +| No authentication | All `.md` URLs are publicly accessible. | +| Partial authentication | `.md` URLs for public pages are publicly accessible. `.md` URLs for protected pages require authentication and respect user group restrictions. | +| Full authentication | All `.md` URLs require authentication and respect user group restrictions. | + ## Keyboard shortcut Press Command + C (Ctrl + C on Windows) to copy a page as Markdown to your clipboard. diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx index 309065c471..e0298b6226 100644 --- a/ai/mintlify-mcp.mdx +++ b/ai/mintlify-mcp.mdx @@ -1,50 +1,51 @@ --- -title: "Mintlify MCP" -description: "Let AI tools directly edit your content on Mintlify with the MCP server. Connect Claude, Cursor, or any MCP client to draft, save, and ship doc changes." +title: "Admin Model Context Protocol (MCP) server" +shortTitle: "Admin MCP" +description: "Give AI tools like Claude and Cursor write access to your Mintlify content and dashboard so they can edit pages, update settings, and open PRs." keywords: ["MCP", "write access", "AI", "editing", "Claude", "Cursor", "branch", "pull request"] --- -## About the Mintlify MCP +## About the admin MCP -The Mintlify MCP server gives AI tools write access to your Mintlify content. Where the [documentation MCP server](/ai/model-context-protocol) lets AI tools read and search your published content, the Mintlify MCP lets them propose changes: edit pages, restructure navigation, update `docs.json`, and open pull requests. +The admin MCP server gives AI tools write access to your Mintlify content and settings. Use it to update content and access your dashboard. With the admin MCP, you can use your preferred AI tools to edit pages, restructure navigation, update `docs.json`, open pull requests, change settings, create workflows, and more. -Connect any MCP client like Claude, Claude Code, or Cursor to the Mintlify MCP to collaborate on your Mintlify content with the same tools you use to write code. When you use the MCP server, all changes happen on a branch and require a pull request to merge. +Connect any MCP client like Claude, Claude Code, or Cursor to the admin MCP server to collaborate on your Mintlify content and settings with the same tools you use to write code. When you use the admin MCP server, all changes happen on a branch and require a pull request to merge. - The Mintlify MCP edits your documentation. Treat it like a developer with commit access. Connect it only from trusted AI tools and review every pull request before merging. + The admin MCP server allows AI tools to access your Mintlify dashboard. Treat it like a coworker with write access. Connect it only from trusted AI tools and review every pull request before merging. -### How the Mintlify MCP differs from the documentation MCP +### How the admin MCP differs from the search MCP -| | Documentation MCP | Mintlify MCP | +| | Admin MCP | Search MCP | | :-- | :-- | :-- | -| **Audience** | Your end users | Your team | -| **Access** | Read and search published pages | Read, edit, restructure, save | -| **Endpoint** | `/mcp` on your site domain | Hosted by Mintlify, scoped to your project | -| **Output** | Search results and page content | Content edits, navigation changes, pull requests | +| **Audience** | Your team | Your end users | +| **Access** | Read, edit, restructure, save, create workflows, manage settings | Read and search published pages | +| **Endpoints** | Hosted by Mintlify, scoped to your project | `/mcp` on your site domain | +| **Output** | Content edits, navigation changes, pull requests, workflow runs | Search results and page content | -## Connect to the Mintlify MCP +## Connect to the admin MCP -Find your Mintlify MCP URL on the [MCP server page](https://dashboard.mintlify.com/products/mcp) in your dashboard. Connecting requires an interactive OAuth login against your Mintlify account. The AI tool exchanges that login for a session token scoped to one project. +You must have an interactive OAuth login against your Mintlify account to connect to the admin MCP. AI tools exchange that login for a session token scoped to one project. - + 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. - 2. Select **Add custom connector**. + 2. Click **Add custom connector**. 3. Add the connector - - Name: Mintlify MCP - - URL:  `https://mcp.mintlify.com` - 4. Select **Add** and complete the OAuth login. + - Name: Admin MCP + - URL: `https://mcp.mintlify.com` + 4. Click **Add** and complete the OAuth login. - Select the attachments button (the plus icon) and choose your Mintlify MCP server. Claude can now call the Mintlify MCP tools while answering your prompt. + Click the attachments button (the plus icon), then select your admin MCP server. Claude can now call the Mintlify admin MCP tools while answering your prompt. - Add the Mintlify MCP server with the Claude Code CLI: + Add the admin MCP server with the Claude Code CLI: ```bash claude mcp add --transport http mintlify https://mcp.mintlify.com @@ -54,8 +55,8 @@ Find your Mintlify MCP URL on the [MCP server page](https://dashboard.mintlify.c 1. Open the command palette with Command \+ Shift \+ P (Ctrl \+ Shift \+ P on Windows). - 2. Search for **Open MCP settings** and select **Add custom MCP**. - 3. In `mcp.json`, add the Mintlify MCP: + 2. Search for **Open MCP settings** and click **Add custom MCP**. + 3. In `mcp.json`, add the admin MCP: ```json { @@ -73,7 +74,7 @@ Find your Mintlify MCP URL on the [MCP server page](https://dashboard.mintlify.c ## How a session works -Every Mintlify MCP session binds to a single Git branch. The flow is: +Every admin MCP session binds to a single Git branch. The flow is: @@ -99,18 +100,18 @@ Every Mintlify MCP session binds to a single Git branch. The flow is: Calling `checkout` again during an active session switches the session to the new branch. Use this to abandon an in-progress draft and start fresh without ending the conversation. -## What the Mintlify MCP can do +## What the admin MCP can do ### Content - **`read`** — Fetch the full MDX of any page on the session branch. -- **`search`** — Find lines matching a substring or regex across every page. +- **`search`** — Find lines matching a substring or regular expression across every page. - **`edit_page`** — Apply a targeted edit to a page. - **`write_page`** — Overwrite a page's full MDX content. ### Navigation -- **`list_nodes`** — Walk the navigation tree, filtered by type, language, version, or tab. +- **`list_nodes`** — Walk the navigation tree with optional filters. Filter by `parentId` (use `recursive: true` to include all descendants), one or more node types, or any division scope: `language`, `version`, `tab`, `dropdown`, `anchor`, `product`, or `item`. Results are paginated through an opaque `cursor`. - **`create_node`** — Add a new page, group, tab, anchor, version, language, product, or dropdown. - **`update_node`** — Update a node's properties in place (rename a group, change an icon, set a default version). - **`move_node`** — Move a node, including renaming a page's path. @@ -131,7 +132,7 @@ Every Mintlify MCP session binds to a single Git branch. The flow is: ## Example prompts -After you connect the Mintlify MCP, you can drive it with natural-language prompts. For example: +After you connect the admin MCP, you can drive it with natural-language prompts. For example: - _"Check out a branch called `add-billing-faq` and create a new page under the FAQ group titled 'Billing'. Draft answers for the five questions in this Linear issue."_ - _"Find every page that mentions the deprecated `legacy_token` field and update the example to use `api_key` instead. Save as a PR titled 'docs: replace legacy\_token references'."_ @@ -145,7 +146,7 @@ After you connect the Mintlify MCP, you can drive it with natural-language promp - The Mintlify MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes. + The admin MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes. diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 9381b3216d..ce131a10eb 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -1,76 +1,75 @@ --- -title: "Model Context Protocol" -description: "Connect your documentation and API endpoints to AI tools like Claude and Cursor with a hosted Model Context Protocol (MCP) server." -keywords: ["MCP", "AI tools", "Claude", "Cursor"] +title: "Search Model Context Protocol (MCP) server" +shortTitle: "Search MCP" +description: "Connect AI tools like Claude, Cursor, and ChatGPT to your hosted search MCP server so they can search and retrieve content from your site." +keywords: ["MCP", "AI tools", "Claude", "Cursor", "search"] --- import { PreviewButton } from "/snippets/previewbutton.jsx" ## About MCP servers -The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates an MCP server from your documentation, preparing your content for the broader AI ecosystem. Any MCP client like Claude, Cursor, Goose, or ChatGPT can connect to your documentation. +The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates a search MCP server for your site, preparing your content for the broader AI ecosystem. Any MCP client like Claude, Cursor, Goose, or ChatGPT can connect to your content. -Your MCP server exposes tools for AI applications to search your documentation and retrieve full page content. Your users must connect your MCP server to their tools. +Your search MCP server exposes tools for AI applications to search and retrieve your content. Your users must connect your search MCP server to their tools. - Looking to let agents edit your content instead of read it? See the [Mintlify MCP server](/ai/mintlify-mcp) for an authenticated MCP server that exposes branching, page editing, navigation, and `docs.json` tools to trusted agents. + Looking to let agents edit your content instead of read it? Use the [admin MCP server](/ai/mintlify-mcp) for an authenticated MCP server that exposes branching, page editing, navigation, and `docs.json` tools to trusted agents. ### How MCP servers work -When an AI application connects to your documentation MCP server, it can search your documentation and retrieve full page content directly in response to a user's prompt. This avoids relying on information from training data or generic web searches. Your MCP server provides access to all indexed content on your documentation site. +When an AI application connects to your search MCP server, it can search your content and retrieve full pages in response to a user's prompt. This avoids relying on information from training data or generic web searches. Your search MCP server provides access to all indexed content on your Mintlify site. -- AI applications can proactively search your documentation while generating a response even if not explicitly asked to search your documentation for an answer. -- AI applications determine when to use the available tools based on the context of the conversation and the relevance of your documentation. -- Each tool call happens during the generation process, so the AI application uses up-to-date information from your documentation to generate its response. +- AI applications can proactively search your content while generating a response even if not explicitly asked to search for an answer. +- AI applications determine when to use the available tools based on the context of the conversation and the relevance of your content. +- Each tool call happens during the generation process, so the AI application uses up-to-date information from your site to generate its response. - Some AI tools like Claude support both MCP and skills. MCP gives access to your documentation content, while skills instruct agents how to use that content effectively. They're complementary and connecting your MCP server gives agents access to both. + Some AI tools like Claude support both MCP and skills. MCP gives access to your content, while skills instruct agents how to use that content effectively. They're complementary and connecting your MCP server gives agents access to both. ### MCP tools -Your MCP server provides two tools that agents can use: +Your search MCP server provides two tools that agents can use: -- **Search**: Searches across your documentation to find relevant content, returning snippets with titles and links. Use this to discover information or find pages matching a query. -- **Query docs filesystem**: Reads and navigates your documentation's virtual filesystem using shell-style commands. Use this to retrieve page content, browse the docs structure, or extract specific sections—including batch reads across multiple pages in a single call. +- **Search**: Searches across your site to find relevant content, returning snippets with titles and links. Use this to discover information or find pages matching a query. +- **Query docs filesystem**: Reads and navigates your site's virtual filesystem using shell-style commands. Use this to browse and retrieve content, or extract specific sections—including batch reads across multiple pages in a single call. -Agents determine when to use each tool based on the context of the conversation. For example, an agent might first search your documentation to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results. +Agents determine when to use each tool based on the context of the conversation. For example, an agent might first search your site to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results. ### MCP resources -Your MCP server also exposes your [skill.md files](/ai/skillmd) as MCP resources. Agents connected to your MCP server can discover and access your skill files without installing them separately. +Your search MCP server also exposes your [skill.md files](/ai/skillmd) as MCP resources. Agents connected to your search MCP server can discover and access your skill files without installing them separately. -`Skill.md` resources appear in the MCP server's resource list and contain the capability descriptions Mintlify generates or that you define in your [custom skill files](/ai/skillmd#custom-skill-files). +`Skill.md` resources appear in the search MCP server's resource list and contain the capability descriptions Mintlify generates or that you define in your [custom skill files](/ai/skillmd#custom-skill-files). ### Search parameters The MCP search tool supports optional parameters that AI applications use to control and refine search results. -- **`pageSize`**: Number of results to return, between 1 and 50. Defaults to 10. -- **`scoreThreshold`**: Minimum relevance score between 0 and 1. Only returns results at or above this threshold. Use this to filter out low-relevance matches. -- **`version`**: Filter results to a specific documentation version. For example, `'v0.7'`. Only returns content tagged with the specified version or content available across all versions. -- **`language`**: Filter results to a specific language code. For example, `'en'`, `'zh'`, or `'es'`. Only returns content in the specified language or content available across all languages. +- **`version`**: Filter results to a specific site version. For example, `'v0.7'`. Only available when your site has multiple versions. Only returns content tagged with the specified version or content available across all versions. +- **`language`**: Filter results to a specific language code. For example, `'en'`, `'zh'`, or `'es'`. Only available when your site has multiple languages. Only returns content in the specified language or content available across all languages. AI applications determine when to apply these parameters based on the context of the user's query. For example, if a user asks about a specific API version, the AI application may automatically apply the appropriate filter to provide more relevant results. -### MCP compared to web search +### Search MCP compared to web search -AI tools can search the web, but MCP provides distinct advantages for documentation. +AI tools can search the web, but the search MCP provides distinct advantages. -- **Direct source access**: Web search depends on what search engines have indexed, which may be stale or incomplete. MCP searches your current indexed documentation directly. +- **Direct source access**: Web search depends on what search engines have indexed, which may be stale or incomplete. The search MCP searches your current indexed content directly. - **Integrated workflow**: MCP allows the AI to search during response generation rather than performing a separate web search. -- **No search noise**: SEO and ranking algorithms influence web search results. MCP goes straight to your documentation content. +- **No search noise**: SEO and ranking algorithms influence web search results. MCP goes straight to your content. -## Access your MCP server +## Access your search MCP server -Mintlify generates an MCP server for your documentation and hosts it at the `/mcp` path of your documentation URL. For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`. +Mintlify generates a search MCP server for your site and hosts it at the `/mcp` path of your site URL. For example, Mintlify's search MCP server is available at `https://mintlify.com/docs/mcp`. -* For public documentation, your MCP server is available to anyone. It searches all indexed public pages. -* For documentation with partial authentication, where some pages are public and others require login, you must enable your MCP server before users can access it. Unauthenticated users can search public content. Users who authenticate can search all content they have permission to access based on their [user groups](/deploy/authentication-setup). -* For documentation where all pages require authentication, you must enable your MCP server before it is available to users. Users must authenticate before connecting to your MCP server. Your MCP server searches only the content each user has access to based on their [user groups](/deploy/authentication-setup). +* For public content, your search MCP server is available to anyone. It searches all indexed public pages. +* For content with partial authentication, where some pages are public and others require login, you must enable your search MCP server before users can access it. Unauthenticated users can search public content. Users who authenticate can search all content they have permission to access based on their [user groups](/deploy/authentication-setup). +* For content where all pages require authentication, you must enable your search MCP server before it is available to users. Users must authenticate before connecting to your search MCP server. Your search MCP server searches only the content each user has access to based on their [user groups](/deploy/authentication-setup). -View and copy your MCP server URL on the [MCP server page](https://dashboard.mintlify.com/products/mcp) in your dashboard. +View and copy your search MCP server URL on the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. MCP server page in the dashboard. @@ -78,14 +77,53 @@ View and copy your MCP server URL on the [MCP server page](https://dashboard.min - Hosted MCP servers use the `/mcp` and `/authed/mcp` paths. Other navigation elements cannot use these paths. + Search MCP servers use the `/mcp` and `/authed/mcp` paths. Other navigation elements cannot use these paths. +### Discovery endpoint + +Mintlify hosts a discovery document at `/.well-known/mcp` for agents and tools to locate your search MCP server without prior configuration. + +`GET /.well-known/mcp` returns a JSON document describing your search MCP server: + +```json +{ + "version": "1.0.0", + "transport": "http", + "url": "https://your-docs.com/mcp", + "servers": [ + { + "name": "public", + "url": "https://your-docs.com/mcp", + "transport": "http", + "authentication": "none" + }, + { + "name": "authenticated", + "url": "https://your-docs.com/authed/mcp", + "transport": "http", + "authentication": "oauth2" + } + ] +} +``` + +| Field | Description | +| --- | --- | +| `version` | The MCP server version. | +| `transport` | The transport protocol. Always `http`. | +| `url` | The default public MCP server URL. | +| `servers` | Available MCP servers. Always includes a `public` entry. When authentication is enabled on your site, also includes an `authenticated` entry. | +| `servers[].name` | Identifier for the server entry. | +| `servers[].authentication` | Authentication method for the server entry. | + +For agent-readiness, the same discovery document is also available at `/.well-known/mcp.json`. Mintlify additionally serves an MCP server card at `/.well-known/mcp/server-card.json` and a list of server cards at `/.well-known/mcp/server-cards.json`. All discovery endpoints are served automatically and don't require configuration. + ### Enable authenticated MCP -If your documentation requires authentication, your MCP server requires users to authenticate before connecting. When a user adds your MCP server URL to their AI tool, they must log in with their existing credentials. After authenticating, a redirect sends them back to their tool. The MCP server only returns content each user has permission to access based on their [user groups](/deploy/authentication-setup). +If your site requires authentication, your search MCP server requires users to authenticate before connecting. When a user adds your MCP server URL to their AI tool, they must log in with their existing credentials. After authenticating, a redirect sends them back to their tool. The MCP server only returns content each user has permission to access based on their [user groups](/deploy/authentication-setup). -If your documentation has partial authentication with both public and protected pages, you have two MCP server endpoints: +If your site has partial authentication with both public and protected pages, you have two search MCP server endpoints: - `/mcp`: Does not require authentication. Returns only public content. Share this with users who need access to public content. - `/authed/mcp`: Always requires authentication. Returns content scoped to each user's permissions based on their [user groups](/deploy/authentication-setup). Share this with users who need access to protected content. @@ -96,7 +134,7 @@ By default, your MCP server is only available for localhost tools. To allow web- - 1. Navigate to the [MCP server page](https://dashboard.mintlify.com/products/mcp) in your dashboard. + 1. Navigate to the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. 2. Click the **Enable MCP Server** toggle. @@ -112,17 +150,17 @@ By default, your MCP server is only available for localhost tools. To allow web- Client credentials let you connect to your authenticated MCP server programmatically without a browser-based login. Use client credentials for server-side integrations, CI/CD pipelines, automated workflows, and any environment where a user cannot complete an interactive OAuth flow. -Client credentials authenticate against the `/authed/mcp` endpoint and return the same content as an authenticated user with access to all pages. +Client credentials authenticate against the `/authed/mcp` endpoint and return all content from public pages and authenticated pages that aren't restricted to specific groups. - 1. Navigate to the [MCP server page](https://dashboard.mintlify.com/products/mcp) in your dashboard. - 2. In the **Client Credentials** section, select **Create credential**. + 1. Navigate to the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. + 2. In the **Client Credentials** section, click **Create credential**. 3. Enter a label for the credential to identify its purpose. 4. Copy the **client ID** and **client secret**. The client secret is only shown once. You cannot retrieve it later. - Send a POST request to your MCP server's token endpoint with your client ID and secret. Your token endpoint is at the `/authed/mcp/oauth/token` path of your documentation URL. + Send a POST request to your MCP server's token endpoint with your client ID and secret. Your token endpoint is at the `/authed/mcp/oauth/token` path of your site's URL. ```bash cURL @@ -185,7 +223,7 @@ Client credentials authenticate against the `/authed/mcp` endpoint and return th #### Managing client credentials -You can manage your client credentials from the [MCP server page](https://dashboard.mintlify.com/products/mcp) in your dashboard. +You can manage your client credentials from the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. - **Delete a credential** to permanently revoke access. This cannot be undone. @@ -200,16 +238,18 @@ To protect availability, Mintlify applies rate limits to MCP servers. | Scope | Limit | Description | | :---- | :---- | :---------- | | Per user (IP address) | 5,000 requests per hour | Limits how frequently a single user can query your MCP server configuration. | -| Search per documentation site (domain) | 10,000 requests per hour | Limits total search tool calls across all users of your MCP server. | -| Query docs filesystem per documentation site (domain) | 10,000 requests per hour | Limits total query docs filesystem tool calls across all users of your MCP server. | -| Authenticated search per documentation site (domain) | 5,000 requests per hour | Limits total authenticated search tool calls across all users of your MCP server. | -| Authenticated query docs filesystem per documentation site (domain) | 5,000 requests per hour | Limits total authenticated query docs filesystem tool calls across all users of your MCP server. | +| Search per site (domain) | 10,000 requests per hour | Limits total search tool calls across all users of your MCP server. | +| Query docs filesystem per site (domain) | 10,000 requests per hour | Limits total query docs filesystem tool calls across all users of your MCP server. | +| Authenticated search per site (domain) | 5,000 requests per hour | Limits total authenticated search tool calls across all users of your MCP server. | +| Authenticated query docs filesystem per site (domain) | 5,000 requests per hour | Limits total authenticated query docs filesystem tool calls across all users of your MCP server. | ## Content filtering and indexing -Your MCP server searches content that Mintlify indexes from your documentation repository. File processing and search indexing control what content is available through your MCP server. +Your MCP server searches content that Mintlify indexes from your project repository. File processing and search indexing control what content is available through your MCP server. + +For sites that require authentication, your MCP server indexes [public pages](/deploy/authentication-setup#make-pages-public) and any pages an authenticated user has permission to access based on their [user groups](/deploy/authentication-setup#restrict-pages-to-specific-user-groups). -For documentation that requires authentication, your MCP server only indexes pages in [public user groups](/deploy/authentication-setup#make-pages-public). For documentation with partial authentication, your MCP server indexes public pages for unauthenticated users and any pages in public user groups. +For sites with partial authentication, unauthenticated users can search public pages. Authenticated users can search public pages and any pages they have permission to access based on their user groups. ### File processing with `.mintignore` @@ -243,13 +283,13 @@ Your users must connect your MCP server to their preferred AI tools. 1. Make your MCP server URL publicly available. 2. Users copy your MCP server URL and add it to their tools. -3. Users access your documentation through their tools. +3. Users access your content through their tools. These are some of the ways you can help your users connect to your MCP server: - Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page of your documentation. + Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page on your site. | Option | Identifier | Description | | :----- | :--------- | :---------- | @@ -261,16 +301,16 @@ These are some of the ways you can help your users connect to your MCP server: - Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + Navigate to your [dashboard](https://app.mintlify.com/products/mcp) and find your MCP server URL. Create a guide for your users that includes your MCP server URL and the steps to connect it to Claude. 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. - 2. Select **Add custom connector**. + 2. Click **Add custom connector**. 3. Add your MCP server name and URL. - 4. Select **Add**. - 5. When using Claude, select the attachments button (the plus icon). + 4. Click **Add**. + 5. When using Claude, click the attachments button (the plus icon). 6. Select your MCP server. @@ -280,7 +320,7 @@ See the [Model Context Protocol documentation](https://modelcontextprotocol.io/d - Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + Navigate to your [dashboard](https://app.mintlify.com/products/mcp) and find your MCP server URL. Create a guide for your users that includes your MCP server URL and the command to connect it to Claude Code. @@ -296,14 +336,14 @@ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-co - Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + Navigate to your [dashboard](https://app.mintlify.com/products/mcp) and find your MCP server URL. Create a guide for your users that includes your MCP server URL and the steps to connect it to Cursor. 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette. - 2. Search for "Open MCP settings". - 3. Select **Add custom MCP**. This opens the `mcp.json` file. + 2. Search for `Open MCP settings`. + 3. Click **Add custom MCP**. This opens the `mcp.json` file. 4. In `mcp.json`, configure your server: ```json @@ -323,7 +363,7 @@ See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing - Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + Navigate to your [dashboard](https://app.mintlify.com/products/mcp) and find your MCP server URL. Create a guide for your users that includes your MCP server URL and the steps to connect it to VS Code. @@ -354,7 +394,7 @@ Connect to the Mintlify MCP server to search this documentation site within your - At the top of this page, select the contextual menu and choose **Connect to Cursor** or **Connect to VS Code** to connect the Mintlify MCP server to the IDE of your choice. + At the top of this page, click the contextual menu, then click **Connect to Cursor** or **Connect to VS Code** to connect the Mintlify MCP server to the IDE of your choice. @@ -363,14 +403,14 @@ To use the Mintlify MCP server with Claude: 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. - 2. Select **Add custom connector**. + 2. Click **Add custom connector**. 3. Add the Mintlify MCP server: - Name: `Mintlify` - URL: `https://mintlify.com/docs/mcp` - 4. Select **Add**. + 4. Click **Add**. - 1. When using Claude, select the attachments button (the plus icon). + 1. When using Claude, click the attachments button (the plus icon). 2. Select the Mintlify MCP server. 3. Ask Claude a question about Mintlify. @@ -404,8 +444,8 @@ To connect the Mintlify MCP server to Cursor, click the **Install in Cursor** bu 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette. - 2. Search for "Open MCP settings". - 3. Select **Add custom MCP**. This opens the `mcp.json` file. + 2. Search for `Open MCP settings`. + 3. Click **Add custom MCP**. This opens the `mcp.json` file. In `mcp.json`, add: @@ -448,7 +488,7 @@ See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/ -### Using multiple MCP servers +### Use multiple MCP servers Users can connect multiple MCP servers to their AI tools. Connected MCP servers do not consume context until the AI calls a search tool. The AI decides when to search based on query relevance, so it doesn't search every connected server for every question. diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index ac34015546..cb3340cf46 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -2,6 +2,7 @@ title: "skill.md" description: "Make your documentation agent-ready with automatically generated skill.md files that describe your product's capabilities for AI agents." keywords: ["AI agents", "skills", "agent skills", "agents"] +boost: 3 --- Mintlify hosts a `skill.md` file at the root of your project that describes what AI agents can do with your product. @@ -190,3 +191,30 @@ The `name` field is a URL-safe slug derived from the `name` in your `skill.md` f ### Individual skill files `GET /.well-known/skills/{name}/skill.md` returns the `skill.md` file for a specific skill identified by its slugified name from the index. + +## Agent card + +Mintlify hosts an [Agent-to-Agent (A2A)](https://a2aproject.github.io/A2A/latest/) agent card at `/.well-known/agent-card.json`. The agent card is a standardized JSON document that helps A2A-compatible agents discover your documentation site and available skills in a single request. + +`GET /.well-known/agent-card.json` returns a JSON document following the [A2A agent card 0.3 schema](https://a2aproject.github.io/A2A/latest/specification/#agent-card). Each entry in the `skills` array corresponds to a skill from your skills discovery endpoints. + +A2A-compatible agents fetch `/.well-known/agent-card.json` to discover your site by name and description, follow `documentationUrl` to retrieve human-readable content, and iterate over `skills` to fetch each `skill.md` file. The card also advertises a `supportedInterfaces` array so agents can negotiate transport before making a request. + +| Field | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------ | +| `protocolVersion` | A2A protocol version. Always `0.3`. | +| `preferredTransport` | Default transport for clients that do not negotiate. Always `HTTP+JSON`. | +| `supportedInterfaces` | Array of `{ url, protocolBinding, protocolVersion }` entries describing how agents can reach your site. | +| `provider` | `{ url, organization }` identifying the documentation site. `organization` is the site title. | +| `defaultInputModes` | Media types the agent accepts as input. Always `["text/plain"]`. | +| `defaultOutputModes` | Media types the agent produces. Always `["text/plain"]`. | +| `capabilities` | Feature flags. Currently `{ streaming: false, pushNotifications: false }`. | +| `skills` | The skills exposed at `/.well-known/agent-skills/`. | + +URLs in the card (`url`, `documentationUrl`, `provider.url`, and each skill URL) use your configured custom domain, so the published card always advertises the canonical domain instead of the `*.mintlify.app` subdomain. + + + If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/.well-known/agent-card.json` to your Mintlify subdomain. + + +The agent card complements [MCP](/ai/model-context-protocol) by providing a lightweight discovery layer that does not require establishing a session. diff --git a/analytics.openapi.json b/analytics.openapi.json index 3e8e91192f..f1ecea56fe 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -16,13 +16,13 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard." } }, "schemas": { "projectId": { "type": "string", - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, "FeedbackResponse": { "type": "object", diff --git a/api-playground/asyncapi-setup.mdx b/api-playground/asyncapi-setup.mdx index 19fba239c8..4c19787cfd 100644 --- a/api-playground/asyncapi-setup.mdx +++ b/api-playground/asyncapi-setup.mdx @@ -98,6 +98,38 @@ To automatically generate pages for all channels in your AsyncAPI schema, add an The `directory` field is optional. If not specified, Mintlify adds the files to the **api-reference** folder of the docs repository. +### Examples with nested groups + +The `asyncapi` property supports nested groups. Mintlify generates the channel pages and adds them to the nested group, alongside any existing pages. + +This is useful when you want to organize WebSocket channels as a subsection of a broader API group, or when you need to combine multiple AsyncAPI specifications under a shared parent group. + +```json +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "groups": [ + { + "group": "Voice API", + "pages": [ + "voice/overview", + { + "group": "Voice API Commands", + "asyncapi": "/path/to/voice-asyncapi.json" + } + ] + } + ] + } + ] +} +``` + +## Schema rendering + +Array schemas and combinatorial schemas (`oneOf`, `anyOf`, `allOf`) expand to show their child attributes inline in the generated channel pages. Readers can open the expandable section for an array item schema or select a tab for each `oneOf`/`anyOf` option to see all nested fields. + ## Channel page If you want more control over how you order your channels or if you want to reference only specific channels, create an MDX file with the `asyncapi` property in the frontmatter. diff --git a/api-playground/complex-data-types.mdx b/api-playground/complex-data-types.mdx index a249669c99..0fae9d13fa 100644 --- a/api-playground/complex-data-types.mdx +++ b/api-playground/complex-data-types.mdx @@ -22,7 +22,7 @@ For detailed specifications of these keywords see the [OpenAPI documentation](ht ### Combining schemas with `allOf` -When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI's reusable [components](https://swagger.io/docs/specification/components/). +When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when you use OpenAPI's reusable [components](https://swagger.io/docs/specification/components/). ```yaml org_with_users: @@ -55,6 +55,10 @@ components: +### `any` and `undefined` types + +Fields typed as `any` or `undefined` render the same way as `oneOf` schemas with a picker that lets users select a concrete shape before sending a request. This allows the API playground to present a meaningful input even when the schema doesn't constrain the value to a single type. + ### Providing options with `oneOf` and `anyOf` When you use `oneOf` or `anyOf`, the options display in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses: diff --git a/api-playground/managing-page-visibility.mdx b/api-playground/managing-page-visibility.mdx index c47cd6b0b2..e114313ec8 100644 --- a/api-playground/managing-page-visibility.mdx +++ b/api-playground/managing-page-visibility.mdx @@ -4,7 +4,7 @@ description: "Control which API endpoints appear in your documentation navigatio keywords: ["x-hidden", "x-excluded", "hide endpoints", "page visibility", "internal endpoints"] --- -For internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation, you can control which OpenAPI operations get published as documentation pages and their visibility in navigation. +You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation. If your pages are autogenerated from an OpenAPI document, manage page visibility with the `x-hidden` and `x-excluded` extensions. @@ -29,7 +29,7 @@ Common use cases for `x-excluded` are: - Deprecated endpoints that you don't want to document. - Beta features that are not ready for public documentation. -## Implementation +## Implementation Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification. diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 3bba0623b6..ca12abe5b4 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -47,7 +47,7 @@ Reference any number of OpenAPI specifications in the navigation element of your ### Describe your API -We recommend the following resources to learn about and construct your OpenAPI specification. +Use the following resources to learn about and construct your OpenAPI specification. - [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax. - [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification. @@ -72,7 +72,7 @@ To enable the API playground, add a `servers` field to your OpenAPI specificatio } ``` -In an OpenAPI specification, different API endpoints are specified by their paths, like `/users/{id}` or simply `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation. +In an OpenAPI specification, different API endpoints are specified by their paths, like `/users/{id}` or `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation. The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown allows users to toggle between servers. If you do not specify a server, the API playground uses simple mode since it cannot send requests without a base URL. @@ -151,6 +151,18 @@ The `x-default` extension supports `apiKey` and `http` bearer security scheme ty You can also use `x-default` on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. +## Let visitors download your spec + +Opt into a "Download API spec" entry in the [page context menu](/organize/settings-structure#contextual) by adding `"download-spec"` to `contextual.options` in your `docs.json`: + +```json +"contextual": { + "options": ["copy", "download-spec", "chatgpt", "claude"] +} +``` + +When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as `api-specs.zip`. The option is hidden for deployments behind `auth` or `userAuth` to prevent leaking spec contents from authenticated docs. + ## Customize your endpoint pages Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension gives you additional control over how your API documentation generates and displays. @@ -402,7 +414,7 @@ To organize multiple OpenAPI specifications in separate sections of your documen ### Selective endpoints -When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications. +When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach lets you generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications. #### Set a default OpenAPI spec @@ -584,3 +596,49 @@ openapi: "openapi.json webhook orderUpdated" ``` The webhook name must exactly match the key in your OpenAPI spec's `webhooks` field. + +## Callbacks + +Callbacks describe out-of-band requests that your API sends to a URL provided by the caller, such as event notifications tied to a specific operation. When an OpenAPI operation defines `callbacks`, Mintlify renders them on the endpoint page in a collapsible section between the request body and response sections. Each callback shows its HTTP method, expression, and reuses the same body and response components as the parent operation. + +For more information on defining callbacks, see [Callbacks](https://spec.openapis.org/oas/v3.1.0#callback-object) in the OpenAPI documentation. + +Define callbacks on the operation in your OpenAPI spec: + +```yaml +paths: + /subscribe: + post: + summary: Subscribe to events + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + callbackUrl: + type: string + format: uri + responses: + "201": + description: Subscription created + callbacks: + orderUpdated: + "{$request.body#/callbackUrl}": + post: + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + orderId: + type: string + status: + type: string + responses: + "200": + description: Callback received +``` diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index cac66b75f2..3daf5241ae 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,7 +1,8 @@ --- -title: "Playground" +title: "API playground overview" description: "Let developers test API endpoints directly in your documentation with an interactive playground that sends real requests and shows responses." keywords: ["interactive", "API", "endpoint testing", "live API requests", "request builder"] +boost: 3 --- The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation. @@ -15,7 +16,7 @@ See [Trigger an update](/api/update/trigger) for an example of the API playgroun The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages. -We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`. +Generate your API playground from an OpenAPI specification for the best results. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`. ## Get started @@ -210,9 +211,9 @@ Both options allow you to: - Add additional content like examples - Control playground behavior per page -We recommend the `x-mint` extension so that all of your API documentation generates automatically from your OpenAPI specification and stays maintained in one file. +Use the `x-mint` extension so that all of your API documentation generates automatically from your OpenAPI specification and stays maintained in one file. -We recommend individual MDX pages for small APIs or when you want to experiment with changes on a per-page basis. +Use individual MDX pages for small APIs or when you want to experiment with changes on a per-page basis. ## Response rendering diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index b4201889ca..c270c3b1c4 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -2,6 +2,7 @@ title: "Troubleshooting" description: "Troubleshoot common issues with API playground configuration, including OpenAPI validation errors, missing endpoints, and auth problems." keywords: ["API troubleshooting", "invalid OpenAPI", "configuration issues"] +boost: 3 --- If your API pages aren't displaying correctly, check these common configuration issues. @@ -15,10 +16,10 @@ If your API pages aren't displaying correctly, check these common configuration To verify your OpenAPI document passes validation: - 1. Visit [this validator](https://editor.swagger.io/) - 2. Switch to the "Validate text" tab - 3. Paste in your OpenAPI document - 4. Click "Validate it\!" + 1. Visit [this validator](https://editor.swagger.io/). + 2. Switch to the **Validate text** tab. + 3. Paste in your OpenAPI document. + 4. Click **Validate it!** If the text box that appears below has a green border, your document has passed validation. This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document diff --git a/api-playground/websocket-playground.mdx b/api-playground/websocket-playground.mdx index 289ce2fb65..b9ef6c30aa 100644 --- a/api-playground/websocket-playground.mdx +++ b/api-playground/websocket-playground.mdx @@ -1,5 +1,5 @@ --- -title: "Playground" +title: "WebSocket playground" description: "Add interactive WebSocket playgrounds to your documentation so users can test real-time connections, send messages, and view event streams." asyncapi: "/asyncapi.yaml channelOne" --- diff --git a/api/agent/v2/create-agent-job.mdx b/api/agent/v2/create-agent-job.mdx index b48a847d40..ef6cd683c1 100644 --- a/api/agent/v2/create-agent-job.mdx +++ b/api/agent/v2/create-agent-job.mdx @@ -7,7 +7,7 @@ keywords: ["agent job", "create", "automation", "automate"] This endpoint creates a background agent job. The job runs asynchronously — use the [get agent job](/api/agent/v2/get-agent-job) endpoint to poll for status updates. -If the agent edits files successfully, a pull request is automatically created and the `prLink` field is populated in the job response. +If the agent edits files successfully, Mintlify creates a pull request and populates the `prLink` field in the job response. ## Rate limits diff --git a/api/agent/v2/get-agent-job.mdx b/api/agent/v2/get-agent-job.mdx index ecae623420..6fcc6650a5 100644 --- a/api/agent/v2/get-agent-job.mdx +++ b/api/agent/v2/get-agent-job.mdx @@ -7,4 +7,4 @@ keywords: ["agent job", "status", "retrieve", "details", "poll"] Poll this endpoint to track the progress of an agent job. The `status` field transitions through `active` → `completed` or `failed`. -Once the agent creates a pull request, the `prLink` field is populated. +After the agent creates a pull request, the `prLink` field contains the link. diff --git a/api/agent/v2/send-message.mdx b/api/agent/v2/send-message.mdx index abbc26e364..06663c457d 100644 --- a/api/agent/v2/send-message.mdx +++ b/api/agent/v2/send-message.mdx @@ -5,7 +5,7 @@ keywords: ["agent job", "message", "follow-up", "send"] --- -Send a follow-up instruction to an existing agent job. The message is processed asynchronously — poll the [get agent job](/api/agent/v2/get-agent-job) endpoint to track progress. +Send a follow-up instruction to an existing agent job. The agent processes the message asynchronously. Poll the [get agent job](/api/agent/v2/get-agent-job) endpoint to track progress. ## Rate limits diff --git a/api/analytics/assistant-caller-stats.mdx b/api/analytics/assistant-caller-stats.mdx index 5a49026884..377fd12c29 100644 --- a/api/analytics/assistant-caller-stats.mdx +++ b/api/analytics/assistant-caller-stats.mdx @@ -7,7 +7,7 @@ keywords: ["analytics", "assistant", "caller", "stats", "export"] ## Usage -Use this endpoint to see how assistant queries are distributed across different caller types. The response breaks down total queries into: +Use this endpoint to see how the system distributes assistant queries across different caller types. The response breaks down total queries into: - **web**: Queries from the documentation site - **api**: Queries from direct API calls diff --git a/api/assistant/create-assistant-message-v2.mdx b/api/assistant/create-assistant-message-v2.mdx index 70e10228a5..e0af95cb14 100644 --- a/api/assistant/create-assistant-message-v2.mdx +++ b/api/assistant/create-assistant-message-v2.mdx @@ -114,6 +114,5 @@ See [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) and [Transpo The assistant API has the following limits: -- 10,000 uses per key per month - 10,000 requests per Mintlify organization per hour - 10,000 requests per IP per day diff --git a/api/assistant/create-assistant-message.mdx b/api/assistant/create-assistant-message.mdx index c040be75e4..e64593511d 100644 --- a/api/assistant/create-assistant-message.mdx +++ b/api/assistant/create-assistant-message.mdx @@ -88,6 +88,5 @@ See [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) in the AI SD The assistant API has the following limits: -- 10,000 uses per key per month - 10,000 requests per Mintlify organization per hour - 10,000 requests per IP per day diff --git a/api/introduction.mdx b/api/introduction.mdx index 960840f5c3..a163fdebf0 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -1,7 +1,8 @@ --- -title: "Introduction" +title: "Mintlify REST API introduction" description: "Use the Mintlify REST API to trigger deployments, embed an AI assistant, export analytics data, and manage documentation programmatically." keywords: ["REST API", "endpoints", "API keys"] +boost: 3 --- The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data. @@ -36,7 +37,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma ## Authentication -Generate API keys on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization--you can use keys across multiple deployments within the same organization. +Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization--you can use keys across multiple deployments within the same organization. You can create up to 10 API keys per hour per organization. diff --git a/api/preview/trigger.mdx b/api/preview/trigger.mdx index aa5a76d051..5144977183 100644 --- a/api/preview/trigger.mdx +++ b/api/preview/trigger.mdx @@ -5,17 +5,13 @@ keywords: ["preview", "preview deployment", "branch preview", "staging"] --- - - Preview deployments are available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=preview-deployments). - - Use this endpoint to programmatically create or update a preview deployment for a Git branch. If a preview already exists for the specified branch, the endpoint triggers a redeployment instead of creating a duplicate. The response includes a `statusId` that you can pass to [Get deployment status](/api/update/status) to track the deployment progress. ## Use cases -- **CI/CD pipelines**: Automatically create preview deployments when pull requests are opened or updated. +- **CI/CD pipelines**: Automatically create preview deployments when users open or update pull requests. - **Scheduled previews**: Build previews from long-running feature branches on a schedule. - **Custom tooling**: Integrate preview creation into internal workflows or Slack bots. diff --git a/assistant/configure.mdx b/assistant/configure.mdx index 7840bea946..a0b928d005 100644 --- a/assistant/configure.mdx +++ b/assistant/configure.mdx @@ -4,7 +4,7 @@ description: "Configure the AI assistant in your Mintlify dashboard: toggle avai keywords: ["assistant", "settings", "deflection", "bot protection", "billing"] --- -Configure the assistant on the [Assistant](https://dashboard.mintlify.com/products/assistant) page of your dashboard. Manage billing and usage on the [Usage](https://dashboard.mintlify.com/settings/organization/usage) page. +Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard. Manage billing and usage on the [Usage](https://app.mintlify.com/settings/organization/usage) page. ## Enable or disable the assistant @@ -55,7 +55,7 @@ Help your users begin conversations with the assistant by adding starter questio The assistant can generate page-specific questions based on the page a user is viewing or you can add persistent questions that are available across pages. -You can add up to three starter questions. Click **Ask AI** for recommended questions based on your documentation. +You can add up to three starter questions. Click **Ask Assistant** for recommended questions based on your documentation. The search suggestions panel in the dashboard with contextual starter questions enabled. @@ -68,7 +68,7 @@ In the Bot Protection section, enable invisible captcha to protect your assistan To enable bot protection: -1. Go to the [Assistant settings](https://dashboard.mintlify.com/products/assistant/settings) page in your dashboard. +1. Go to the [Assistant settings](https://app.mintlify.com/products/assistant/settings) page in your dashboard. 2. In the **Bot Protection** section, toggle **Invisible Captcha** on. Changes take up to 10 minutes to propagate. @@ -79,31 +79,24 @@ Changes take up to 10 minutes to propagate. ## Manage billing -The assistant uses tiered message allowances. A message is any user interaction with the assistant that receives a correct response. If you have unused messages, up to half of your message allowance can carry over to the next billing cycle. For example, if you have a 1,000 message allowance and you use 300 messages, 500 messages carry over to the next billing cycle giving you a total of 1,500 messages for the next billing cycle. +The assistant runs on credits. Each assistant message consumes credits, where a message is any user interaction with the assistant that receives a response. See [Credit pricing](/credits) for more information. -By default, the assistant allows overages. You can disable overages to avoid incurring additional costs for usage beyond your tier. If you reach your message allowance with overages disabled, the assistant is unavailable until your message allowance resets. If you allow overages, each message beyond your allowance incurs an overage charge, but occasional overages may be cheaper than upgrading to a higher tier depending on your usage. +### Change your credit tier -### Change your assistant tier +1. Go to the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. +2. In the **Credit packages** section, select a tier from the dropdown menu. +3. Confirm the change to proceed to checkout. -Assistant tiers determine your monthly message allowance and pricing. - -View and change your current tier on the [Usage](https://dashboard.mintlify.com/settings/organization/usage) page of your dashboard. - -In the **Spending Controls** section, select your preferred tier from the dropdown menu. +### Allow overages -**Upgrade your tier:** -- Your new message allowance is available immediately. -- You pay a prorated difference for the current billing cycle. +Overages are disabled by default. With overages disabled, the assistant is unavailable once you reach your credit allowance and remains unavailable until your allowance resets. -**Downgrade your tier:** -- Your message allowance updates immediately. -- Pricing changes take effect at the start of your next billing cycle. -- Unused messages from your current tier **do not** carry over. +To allow overages, enable them in the **Spending controls** section of the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. If you enable overages, each credit beyond your allowance incurs an overage charge. -### Allow overages +### Set usage alerts -If you want to disallow overages, disable them in the **Billing Controls** section of the [Usage](https://dashboard.mintlify.com/settings/organization/usage) page of your dashboard. +In the **Spending controls** section of your dashboard, set usage alerts to receive an email when you reach a certain percentage of your credit allowance. -### Set usage alerts +### Higher credit volumes -In the Billing Controls section, set usage alerts to receive an email when you reach a certain percentage of your message allowance. +For plans larger than 10,000 credits per month, [contact sales](mailto:sales@mintlify.com) to discuss custom credit packages. diff --git a/assistant/index.mdx b/assistant/index.mdx index 6039b6fc34..329c031389 100644 --- a/assistant/index.mdx +++ b/assistant/index.mdx @@ -1,18 +1,19 @@ --- title: "Assistant" description: "Add an AI-powered chat assistant to your documentation site that answers user questions, cites sources, and generates code examples on demand." -keywords: ["chat", "RAG", "user support", "multimodal"] +keywords: ["chat", "user support", "multimodal"] +boost: 3 --- - The assistant is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=assistant) and is enabled by default for those plans. + The assistant is enabled by default. All organizations receive 5,000 trial credits shared across the assistant, agent, and workflows. See [Manage billing](/assistant/configure#manage-billing) for more information about credit tiers and options. ## About the assistant The assistant answers questions about your documentation through natural language queries. Users access the assistant on your documentation site, so they can find answers quickly and succeed with your product even if they don't know where to look. -The assistant uses agentic RAG (retrieval-augmented generation) with tool calling. When users ask questions, the assistant: +The assistant uses tool calling to answer questions. When users ask questions, the assistant: * **Searches and retrieves** relevant content from your documentation to provide accurate answers. * **Builds context** from the page a user is viewing when they ask questions. @@ -37,7 +38,7 @@ You can [set a deflection email](/assistant/configure#set-deflection-email) so t Use assistant insights to understand how users interact with your documentation and identify improvement opportunities. -The [assistant page](https://dashboard.mintlify.com/products/assistant) shows usage trends for the month to date. View more detailed insights on the [analytics](/optimize/analytics#assistant) page. +The [assistant page](https://app.mintlify.com/products/assistant) shows usage trends for the month to date. View more detailed insights on the [analytics](/optimize/analytics#assistant) page. ## Make content AI ingestible diff --git a/assistant/use.mdx b/assistant/use.mdx index 5423353f58..fabdac8b7b 100644 --- a/assistant/use.mdx +++ b/assistant/use.mdx @@ -4,7 +4,7 @@ description: "Open the assistant with keyboard shortcuts, highlighted text, code keywords: ["assistant", "keyboard shortcut", "file attachments", "local preview", "URL parameters"] --- -Users have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. Users can ask any question and the assistant searches your documentation for an answer. If the assistant cannot retrieve relevant information, it responds that it cannot answer the question. +You have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. You can ask any question and the assistant searches your documentation for an answer. If the assistant cannot retrieve relevant information, it responds that it cannot answer the question. ## Use the assistant in local preview @@ -81,7 +81,7 @@ https://yourdocs.mintlify.app/quickstart?assistant=How%20do%20I%20get%20started% ## Highlight text -Highlight text on a page and click the **Add to assistant** pop up button to open the assistant chat panel and add the highlighted text as context. You can add multiple text snippets or code blocks to the assistant's context. +Highlight text on a page and click the **Add to assistant** button to open the assistant chat panel and add the highlighted text as context. You can add multiple text snippets or code blocks to the assistant's context. The Add to assistant button above highlighted text in light mode. @@ -90,11 +90,11 @@ Highlight text on a page and click the **Add to assistant** pop up button to ope ## Code blocks -Click the **Ask AI** button in a code block to open the assistant chat panel and add the code block as context. You can add multiple code blocks or text snippets to the assistant's context. +Click the **Ask Assistant** button in a code block to open the assistant chat panel and add the code block as context. You can add multiple code blocks or text snippets to the assistant's context. -The Ask AI button in a code block in light mode. -The Ask AI button in a code block in dark mode. +The Ask Assistant button in a code block in light mode. +The Ask Assistant button in a code block in dark mode. ## File attachments diff --git a/changelog.mdx b/changelog.mdx index 8d38ff5500..fcf93f24d3 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -5,11 +5,161 @@ rss: true noindex: true --- - + + ## Editor + + More ways to edit and configure your docs directly from the [web editor](https://www.mintlify.com/docs/editor): + + - **Visual `docs.json` editor:** A redesigned configuration editor lets you edit `docs.json` visually and sync changes back to the navigation tree. + - **Page settings panel:** The new page settings panel lets you view and edit frontmatter in the file explorer view. + - **Hide branches toggle:** A new toggle hides branch indicators in the editor view for a cleaner workspace. + - **Better link editing:** Editing inline links is faster with an improved link editor experience. + - **Fullscreen table mode:** Edit large tables in a dedicated fullscreen view. + - **Drag and drop Markdown:** You can now drag and drop Markdown files into the editor to upload them. + - **Brand icons in icon picker:** Brand icons are now available alongside the rest of the icon library. + + ## Editor agent + + - **Searches Mintlify docs:** The agent can now search the Mintlify documentation while you work in the editor, so you're always connected to the source of truth for Mintlify while updating content. + - **Edit and delete non-content files:** The agent can manage non-content files in your repository in addition to pages. + - **File attachments:** Attach files directly to the agent. + - **Interrupt mid-stream:** Stop the agent while it's streaming a response if you want to redirect it. + + ## Workflows + + - **Draft improvements from user feedback:** This new workflow reviews recent [page feedback](/optimize/feedback) and opens pull requests based on what users report. + - The **update from code changes** workflow (formerly sync content with code) defaults to run on a schedule rather than triggering on every code change. When it runs, the agent scans all code changes since the last run and opens one PR per related set of documentation updates. If a PR is still open from a previous workflow run, new changes are appended to it rather than creating a new PR. This means a release worked on over several weeks produces a single docs PR to review instead of one per commit. + - Workflow titles and copy across the dashboard have been refreshed for clarity. + + ## API playground + + - **Callbacks on API reference pages:** OpenAPI `callbacks` now render on API reference pages so readers can see the requests your API sends back. + - **Download API spec:** A new **Download API spec** option is available from the contextual menu on API reference pages. + + ## Admin MCP + + Agents that connect to the admin MCP can now read and modify most dashboard settings directly. This lets you configure your entire Mintlify setup without touching the dashboard and gives AI agents direct access to your analytics data. Supported operations include: + + - Enabling and disabling workflows + - Creating custom workflows + - Managing authentication settings + - Configuring custom domains + - Reading and analyzing analytics data + + ## Agent discoverability + + - **MCP server card:** Mintlify now serves an MCP server card at the well-known paths MCP scanners probe, including server info and customer name, making it easier for clients to discover your MCP server. + - **Content-Signal directives:** Tenant `robots.txt` files now include Content-Signal directives to communicate AI usage preferences to crawlers. + - **AI discoverability for partially authenticated sites:** Deployments with [partial authentication](/deploy/authentication-setup) now serve `sitemap.xml`, `llms.txt`, `llms-full.txt`, and `robots.txt` publicly, so AI crawlers and agents can discover your content even when parts of your site require authentication. + + ## Improvements + + - Switch organizations without signing out: You can now move between organizations with one click. No more re-authenticating to switch projects. + - Snippet variables in code blocks: [Reusable snippets](/create/reusable-snippets) now support variables inside code blocks, so you can parameterize examples consistently. + + ## Bug fixes + + - Custom heading IDs now preserve casing (camelCase, snake_case, kebab-case). + - Navigation breadcrumbs render above page-level hits in search results. + - Enum defaults pre-populate when you add new array items in the API playground. + - `.xml` files are now treated as valid link targets by the broken-links checker. + - Changelog pages now include an RSS feed discovery meta tag so readers can subscribe directly from the page. + - Bullet point behavior in the editor is fixed, including continuing and exiting lists. + - Pasting copied web images no longer creates duplicate broken image nodes. + - Large editor media uploads now use direct-to-S3 presigned URLs, bypassing the previous 4.5 MB function payload limit. + - GitHub edit links now work correctly for `.md` pages. + - Slash commands and the file settings sheet behave correctly in the file tree. + + + + ## Web Editor + + We've continued to enhance our web editor with a number of functionality and UI improvements. + + - **More editable file types:** A broader set of file extensions can now be opened and edited directly in the web editor, while executable uploads are blocked for safety. + - **Agent chat panel relocated:** The agent chat panel has been repolished and now sits to the left of the file explorer, making it easier to chat and navigate at the same time. + - **Editor settings:** A new settings panel and redesigned settings modal give you a single place to manage per-editor preferences. See [Web editor](https://www.mintlify.com/docs/editor). + - **File-tree navigation by default:** Newly onboarded users start in the file-tree view instead of the legacy list view. + - **Browser tab titling:** The browser tab name now dynamically updates to match the active file, so you always know which file you're editing. + + ## Workflows + + - New **Draft improvements from assistant conversations** workflow reviews trends from user questions and suggests documentation updates to address gaps. See [Workflows](/workflows/reference#draft-improvements-from-assistant-conversations). + - **Context repositories** can now be configured directly for some workflows so you can add the repos a workflow should reference while running. + - Workflow settings now open in a **side panel** instead of a modal, making it easier to tweak settings while reviewing Workflow Runs. + + ## Search Improvements + + - **Maximum search results** lets you control how many results the in-product search bar returns per query. Tune this alongside search boosts to fit how readers navigate your docs. See [Search](https://www.mintlify.com/docs/optimize/search#maximum-search-results) for details. + - **Searchable hidden tabs and groups:** Hidden tabs and groups now support a `searchable: true` option that exposes their descendant pages to in-product search, the sitemap, and AI context. Use it when you rely on hidden tabs in your navigation (for example, for per-product isolated sidebars) and still want those pages indexed. See [Hidden pages](https://www.mintlify.com/docs/organize/hidden-pages#include-pages-under-specific-hidden-tabs-or-groups) for details. + + ## Improvements + + - **Slack Agent**: The [Slack agent](https://www.mintlify.com/docs/agent/slack) now supports **GitLab** alongside GitHub for repository-aware workflows. + - **Sidebar Navigation:** Sidebar navigation state and scroll position are now preserved across page navigation. + - **Accessibility:** Accessibility improvements across docs, including the table of contents and mobile agent panel. + - **AsyncAPI schemas**: Array and combinatorial (`oneOf` / `anyOf` / `allOf`) schemas now expand to show their child attributes in the API reference. + - **API playground**: `any` and `undefined` types are now handled like `oneOf` schemas, letting users pick a concrete shape when sending a request. + + + ## Web Editor + + The [editor](https://www.mintlify.com/docs/editor) has been redesigned for live collaboration, parsing, and stability. Additional improvements include: + + - **Agent panel**: Chat with the editor agent inline — attach files, view per-session diffs, leave feedback, and jump to the page the agent edited. + - **Add to Assistant**: Send highlighted content straight to the [Assistant](https://www.mintlify.com/docs/assistant) from the editor toolbar. + - **File tree**: Create folders, create unlisted pages, and rename items in the file tree. Add unlisted Markdown into the navigation tree, and open unlisted Markdown and media files directly from the tree. + + ## Improvements + + - **Workflows**: New **Add GitHub repositories** link in the Workflows repository dropdown makes it easier to connect additional repositories without leaving the page. The Workflow Runs tab now defaults to **All runs** when nothing currently needs review, and a **View all runs** button on the empty state clears active filters in one click. + - **Mintlify Agent**: The [Mintlify agent](https://www.mintlify.com/docs/agent/slack) can now be installed in your Slack workspace even without having a Mintlify-hosted deployment. Additionally, viewer-role users can now ask questions and get answers using read-only tools, and the agent now uses prior thread images and message reactions as additional context. + - **Schema graph callbacks**: API reference pages now render OpenAPI `callbacks` in the schema graph. + - **Danish language support** added. + + ## Bug fixes + + - Restored the editor's agent history panel. + - Fixed live collaboration for hidden blocks in the editor. + - Fixed cases where the source editor would misparse content. + - Fixed `Cmd+B` so it toggles the nav sidebar from anywhere in the dashboard. + - Fixed keyboard navigation and default open state for the agent panel. + - Fixed thumbs-up/down feedback being double-counted in the analytics dashboard. + - The chat CSV export now always includes the **Query category** column. + - Fixed an issue where root pages could be incorrectly stamped as public. + + + + ## Expanded MCP content access + + Authenticated [MCP servers](/ai/model-context-protocol) now return more of your content to authorized users. Authenticated users can search public pages plus any pages they have permission to access based on their user groups, instead of being limited to public pages only. [Client credentials](/ai/model-context-protocol#client-credentials) return all public pages and authenticated pages that aren't restricted to specific groups. + + The Mintlify MCP `list_nodes` tool now supports filtering by `parentId` (with optional `recursive` traversal), multiple node types, and additional division scopes including `dropdown`, `anchor`, `product`, and `item`. Results are paginated through an opaque cursor. See the [Mintlify MCP](/ai/mintlify-mcp) documentation for more details. + + ## Assistant credit packages + + The [assistant](/assistant) billing experience has been updated to use credit-based packages across all plans, with consistent terminology in the dashboard and usage controls. No changes to existing credit balances or usage. + + ## AsyncAPI nested groups + + The `asyncapi` property now supports [nested groups](/api-playground/asyncapi-setup#examples-with-nested-groups), so you can generate channel pages inside a subsection of a broader API group or combine multiple AsyncAPI specifications under a shared parent. + + ## Improvements + + - [Slack agent](/agent/slack) now requests permission requests to run third-party action such as sending an email or creating a ticket. + - The [editor](/editor) now lets you drag images and videos from the navigation tree directly onto a page to embed existing media inline. + - Mermaid diagrams in the editor now support a fullscreen mode for easier editing of complex diagrams. + - The custom domain dashboard now displays both verification `TXT` records (`_acme-challenge` and `_cf-custom-hostname`) with live verification status, so you can confirm DNS is correct before pointing your `CNAME` at Mintlify. See [custom domain](/customize/custom-domain) for more details. + - TLS certificate provisioning for [custom domains](/customize/custom-domain#automatic-tls-provisioning) is now handled directly by Mintlify. + - GitLab-connected deployments can now revalidate their Git source from the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page by clicking the **Active** badge, useful when branch options or configuration appear stale. + - The [feedback dashboard](/optimize/feedback) detailed feedback view now only shows submissions that include written comments, making qualitative feedback easier to scan. + + + ## Workflows - Workflows have been rebuilt with a new [dashboard experience](https://dashboard.mintlify.com/products/workflows?tab=workflows). + Workflows have been rebuilt with a new [dashboard experience](https://app.mintlify.com/products/workflows?tab=workflows). - **Optimized workflow templates**: Mintlify maintains prompts for common content creation and maintenance tasks. Turn on these workflows and let the agent handle the rest. Mintlify routinely improves the prompts so that you don't have to. - **Quicker setup**: Toggle on a workflow and adjust any optional settings. No more YAML configuration or iterating on Markdown prompts. @@ -19,14 +169,14 @@ noindex: true ## Editor - The [editor](https://dashboard.mintlify.com/editor) is redesigned for better collaboration and improved stability. The editor now supports real-time collaboration, automatic saving across devices, and improved syncing. + The [editor](https://app.mintlify.com/editor) is redesigned for better collaboration and improved stability. The editor now supports real-time collaboration, automatic saving across devices, and improved syncing. See the [editor](/editor) documentation for more details. The classic editor sunsets in May 2026. ## Agent score - + [Agent score](http://mintlify.com/score) evaluates how agent-ready your site is. It is a free tool built on the open source [AFDocs spec](https://afdocs.dev) with additional checks based on Mintlify's research and best practices. ## Mintlify MCP @@ -38,15 +188,15 @@ noindex: true ## Agent connections Ask the agent in [Slack](/agent/slack) to set up any third-party integration that it should use as context. Prompt the agent to connect to a service like GitHub, Jira, Notion, Google Drive, Confluence, or any other service that you use. - + The agent uses [Composio](https://docs.composio.dev/toolkits) to support a broad catalog of third-party services, including issue trackers, knowledge bases, CRMs, and developer tools. See the [Composio toolkits catalog](https://docs.composio.dev/toolkits) for the full list of supported services. ## Section-level search boost - Search indexing now supports section-level boosts and page-level boosts, letting you promote specific content so it ranks higher for relevant queries. See the [search boost](/optimize/search-boost) documentation for more details. + Search indexing now supports section-level boosts and page-level boosts, letting you promote specific content so it ranks higher for relevant queries. See the [Search](/optimize/search#boost-search-ranking) documentation for more details. ## Improvements - + - Control whether OpenAPI-generated reference pages are included in your [Markdown export](/ai/llmstxt) and `llms-full.txt` - Search improvements: matched query terms highlighted in search results, search indexes content inside alt text, tag-based search filters are case-insensitive, and snippets no duplicate page titles. - Banner components support more types and per-user dismissibility. @@ -68,11 +218,9 @@ noindex: true - Fixed search results not finding bare queries like `search`. - Fixed self-serve deployment errors in the dashboard. - Fixed a workflow card toggle that could blank the dashboard page. - - - + ## Preview Deployment API A public API for generating preview deployments is now available. Use it to trigger previews from your own tooling—useful when your Git workflow doesn't map cleanly to standard branch-based preview triggers. See [Trigger preview deployment](/api/preview/trigger) for more details. @@ -112,11 +260,9 @@ noindex: true - Fixed symlink handling for skill files stored outside the content directory. - Fixed the Luma integration table of contents position. - Fixed deployment URLs not including the page href for direct links. - - - + ## Visibility component The new [`Visibility`](/components/visibility) component lets you show different content to human readers and AI agents on the same page. Wrap content in `` to display it only on the web version of a page or `` to include it only in [Markdown output](/ai/markdown-export) consumed by AI tools. Useful for tailoring instructions, examples, or formatting to each audience without maintaining separate pages. @@ -147,6 +293,7 @@ noindex: true - Custom `skill.md` files in your repository are now detected correctly during deployment. ## Deprecations + - File-based workflows are deprecated. Create workflows from the dashboard instead. Existing workflows from files continue to work, but new workflows must be created in the dashboard. ## Bug fixes @@ -159,15 +306,13 @@ noindex: true - Fixed the `mint analytics feedback` CLI command sending incorrect feedback type values. - Fixed a shadow artifact on number stepper buttons. - Fixed client-side navigation for related links. - - - + ## CLI analytics The [`mint analytics`](/cli/analytics) command lets you view traffic, search queries, user feedback, and assistant conversations from the terminal for better integration with agents. - + Use subcommands to explore specific data: - `mint analytics stats` — views, visitors, searches, feedback, and assistant usage for a date range @@ -193,7 +338,7 @@ noindex: true ## Client credentials for authenticated MCP [Client credentials](/ai/model-context-protocol#client-credentials) are now available for authenticated MCP servers. Use client credentials to connect programmatically without a browser-based login—ideal for server-side integrations, CI/CD pipelines, and automated workflows. Create and manage credentials from the MCP server page in your dashboard. - + ## Improvements - The [`mint new`](/cli/commands#mint-new) command now supports creating projects from pre-defined templates with the `--template` flag. @@ -220,12 +365,10 @@ noindex: true - Fixed an issue where switching branches could leave the editor in an inconsistent state. - Fixed API response example generation failing for certain OpenAPI schema types. - Fixed pages marked as hidden still appearing in the sitemap. - - - - ## get_page MCP tool + + ## get\_page MCP tool [MCP servers](/ai/model-context-protocol) that Mintlify generates now include a `get_page` tool that lets AI agents fetch full page content by path. Agents can retrieve complete documentation pages for deeper context beyond search results. @@ -259,19 +402,17 @@ noindex: true - Fixed [workflow](/workflows) automerge toggle not properly disabling when set to off. - Fixed API playground including optional object fields with required children in generated request bodies. - Fixed keyboard activation for the feedback analytics table selection checkbox. - - - + ## Linear integration Connect your Linear workspace from the agent settings page to give the agent access to your Linear issues. The agent can reference issues and comments as context when generating documentation updates or you can delegate issues to the agent to directly in your Linear workspace. ## Notion integration - Connect your Notion workspace from the agent settings page to give the [agent](/agent/notion) read access to your Notion content. The agent can reference Notion pages as context when generating documentation updates. - + Connect your Notion workspace from the agent settings page to give the [agent](/agent) read access to your Notion content. The agent can reference Notion pages as context when generating documentation updates. + ## Offline export Package your entire documentation site into a self-contained zip archive with the [`mint export`](/deploy/export) CLI command. Share the zip so your users can view your docs in their browser without an internet connection or a Mintlify account. @@ -321,11 +462,9 @@ noindex: true - Fixed navigation item badge wrapping. - Fixed API key being erased during prefill examples. - Fixed linked code snippets in cards not being clickable. - - - + ## Authenticated MCP route A new authenticated route is available for [MCP](/ai/model-context-protocol) servers, enabling secure search over documentation sites with authentication enabled. @@ -367,14 +506,12 @@ noindex: true - Fixed nested block elements inside lists. - Fixed code block tooltip appearing for Prompt and Mermaid components. - Fixed hidden page children not appearing in decorated navigation. - - - + ## Workflow templates - Create [workflows](/workflows) faster with pre-built templates in the [dashboard](https://dashboard.mintlify.com/products/workflows). Choose from templates for changelog generation, API docs sync, feature documentation drafts, broken link detection, SEO audits, and more. Templates include optimized prompts and trigger configurations to get you started quickly. + Create [workflows](/workflows) faster with pre-built templates in the [dashboard](https://app.mintlify.com/products/workflows). Choose from templates for changelog generation, API docs sync, feature documentation drafts, broken link detection, SEO audits, and more. Templates include optimized prompts and trigger configurations to get you started quickly. ## Workflow CLI command @@ -414,11 +551,9 @@ noindex: true - Fixed recursive workflow runs - Fixed agent from re-creating a PR when prompted for follow up changes - Fixed agent session errors for multi-lingual sessions - - - + ## Auto-generate documentation from public repositories [Auto-generate a complete documentation site](https://mintlify.com/explore) from any public GitHub repository. Replace `github.com` with `mintlify.com` in any public repository URL to instantly preview generated documentation. If you are the repository owner, claim the documentation site to add it to your Mintlify organization and customize it. @@ -453,16 +588,14 @@ noindex: true - Fixed branch names with underscores not working in the editor. - Fixed link border colors in callout components. - Fixed mobile zoom behavior for input fields. - - - + ## Workflows Automate documentation tasks with [workflows](/workflows). Set up scheduled or event-triggered automations that run the agent to update your documentation. - Workflows are in beta and currently available on [Enterprise plans](https://mintlify.com/pricing). Available on Pro plans soon. + Workflows are in beta and available on all plans. ## Comments and suggestions @@ -489,11 +622,9 @@ noindex: true - Fixed frontmatter parsing in the editor. - Fixed table tooltip positioning. - Fixed dark/light image rendering without Frame wrapper. - - - + ## `assistant.md` and `agent.md` support Use `.mintlify/Assistant.md` and `.mintlify/AGENTS.md` files in your repository to customize the agent and assistant behaviors. See [Customize assistant behavior](/assistant/customize) and [Customize agent behavior](/agent/customize) for more information. @@ -514,11 +645,9 @@ noindex: true - Fixed logout timeout issues. - Fixed accordion ID deduplication to prevent duplicate anchor links. - Improved SVG sanitization for better security. - - - + ## Prompt component Use the [prompt](/components/prompt) component to display copyable prompts. Designed for sharing AI prompts and supports opening prompts directly in Cursor. @@ -548,11 +677,9 @@ noindex: true ## Feedback email capture The [feedback](optimize/feedback) form now includes an optional email field so users can provide contact information when submitting feedback. - - - + ## Self-serve SSO configuration Enterprise customers can now configure SAML SSO (Okta or Microsoft Entra) directly from the dashboard, including just-in-time (JIT) provisioning, provider switching, and connection removal. @@ -575,11 +702,9 @@ noindex: true - Renaming files via the configuration sheet in the editor now properly saves changes. - MDX parsing errors, like an unclosed `` tag, now update dynamically as you fix them instead of persisting incorrectly across reloads. - Drag-and-drop handles in the editor now align correctly with different content types like headings or paragraphs with consistent sizing and better hit areas. - - - + ## Skills installation simplified Install [skill.md files](/ai/skillmd) using just a documentation URL. No path to the `skill.md` file needed. @@ -598,7 +723,7 @@ noindex: true - What-you-see-is-what-you-get title and description editing for Cards, Accordions, and Steps components - Hide and unhide pages from your navigation - Local image support in live preview - - Code block triggering with ``` + - Code block triggering with - More precise drag handle selection - Stability improvements @@ -628,11 +753,9 @@ noindex: true - Fixed an issue where page "last modified" dates updated incorrectly during global config changes. - Fixed authentication issues affecting index pages from properly rendering. - GitHub status is now properly surfaced during onboarding if GitHub is down. - - - + ## `skill.md` auto-generation Documentation sites now auto-generate a `skill.md` file based on your API references, guides, and features to give AI agents a comprehensive skills file with context on how to help people use your product. `skill.md` replaces the `install.md` approach with more structured capabilities and wider adoption. If you have a custom `skills.md` file at the root of your documentation repository, it replaces the auto-generated version. See [skill.md](/ai/skillmd) for more information. @@ -650,14 +773,13 @@ noindex: true - Combined authentication, partial authentication, and personalization into a single authentication experience. See [Authentication setup](/deploy/authentication-setup) for more information. - Hidden pages now automatically receive `noindex` meta tags for better SEO control. - Added markdown support for image captions. - - - + ## `install.md` auto-generation + Documentation sites now auto-generate an `install.md` file that aggregates installation-related pages like quickstarts, getting started, installation, and setup guides for AI agents. If you have a custom `install.md` file in your documentation repository, it takes priority over the auto-generated version. - + ## Web editor improvements - **Live preview**: See real-time changes as you edit your documentation in the web editor. Live previews show your site exactly as it appears when published, without creating a preview deployment. @@ -682,10 +804,9 @@ noindex: true - Fixed images not displaying on initial load after uploading in the editor. - Fixed code styling within card links. - Fixed `.md` files incorrectly overwriting `.mdx` files. - - + ## Implicit snippets Snippets now work without explicit configuration. Previously, you needed to define snippets in a specific `/snippets` directory. Now, you can import any file as a snippet from anywhere in your docs for more flexible content reuse. See [Reusable snippets](/create/reusable-snippets) for more information. @@ -704,10 +825,9 @@ noindex: true - **Mermaid controls**: Interactive controls for [Mermaid diagrams](/components/mermaid-diagrams) to navigate large diagrams. - **URL parameters for search and assistant**: Open pages with the search modal prefilled with `?search=` or the assistant with `?assistant=`. User query parameters for direct linking and sharing knowledge. - **Profile name editing**: Users can now edit their first and last name in profile settings. - - + ## Web editor improvements The [web editor](/editor/index) now has a more intuitive interface and new capabilities. @@ -742,10 +862,9 @@ noindex: true - Fixed links in assistant opening in new windows instead of the same window. - Fixed Markdown link rendering in assistant responses. - Fixed header slug character handling for special characters. - - + ## Agent improvements - Added support for reading [custom instructions](/agent/customize) from an `AGENTS.md` file. @@ -776,12 +895,11 @@ noindex: true - Added support for Polish, Uzbek, and Hebrew languages. - UI elements in the API playground, including "Try it" and "Send" buttons, are now localized across all supported languages. - - + ## Agent suggestions - + The agent can now monitor Git repositories and suggest documentation updates. When user-facing code changes are detected, suggestions appear in the agent panel. Suggestions include the relevant pull request and a list of proposed documentation updates. Add suggestions as context for the agent to create pull requests or dismiss them. ## Q&A bot in Slack @@ -813,32 +931,28 @@ noindex: true - Fixed loading states and date range values for analytics page. - Folders in the web editor now properly maintain their open/closed state when other folders are opened or closed. - Fixed long API page titles overflowing instead of wrapping. - - + ## Preview widget Preview deployments now include an interactive widget that displays all changed files in the deployment. The widget appears as a floating button in the bottom-right corner and provides: - - One-click navigation to changed pages. - - Searchable list of all changed files with status badges (added, modified, removed). + - One-click navigation to changed pages. + - Searchable list of all changed files with status badges (added, modified, removed). The widget is automatically enabled on all preview deployments and helps reviewers quickly navigate to modified content. - - + ## Last modified dates You can now display "last modified" timestamps on all pages in your documentation. Enable this feature by setting the [`timestamp`](/organize/settings-seo#metadata) flag in your `docs.json` settings. When enabled, each page will automatically show when it was last updated, helping readers understand how current the content is. - - - + ## Web editor improvements - Fixed image uploading from visual mode in the editor. Now images upload with correct paths and improved path resolution handles absolute and relative paths. @@ -859,19 +973,17 @@ noindex: true - Fixed hash handling for URLs and table of contents to properly highlight the active page when accessing the root path with an index page. - Added ability to disable 404 page recommendations via configuration. - Fixed a bug in the API playground where boolean `false` and numeric `0` values in query parameters would be filtered out and not appear in the generated API request. - - + ## Assistant query bucketing - [Assistant insights](https://dashboard.mintlify.com/products/assistant) now automatically groups similar queries together into question categories, which makes it easier to identify patterns in what your users are asking about. - - Click a category to see all conversations in the category and drill down into individual conversations where you can see user queries, assistant responses, and sources cited. + [Assistant insights](https://app.mintlify.com/products/assistant) now automatically groups similar queries together into question categories, which makes it easier to identify patterns in what your users are asking about. + Click a category to see all conversations in the category and drill down into individual conversations where you can see user queries, assistant responses, and sources cited. - + ## .mintignore support - Added `.mintignore` file support to exclude specific files and directories from being processed and published to your documentation site. @@ -879,17 +991,15 @@ noindex: true - Excluded files don't appear in published docs, aren't indexed for search, and aren't accessible to visitors. Learn more in the [.mintignore documentation](/organize/mintignore). - - + ## Vale version upgrade - Upgraded backend dependencies to use Vale version 3.11.2-r5, bringing native MDX support to the Vale CI check feature. - - + ## API playground improvements - Fixed issue where response section would disappear when switching between endpoints with different response codes. The playground now properly resets to the first available response code when navigating to a new endpoint. @@ -907,10 +1017,9 @@ noindex: true ## CLI improvements - Added error message for users running `mint dev` on Node.js versions below 20.17. Users are guided to upgrade to an LTS version. - - + ## New features - **Badge component**: New Badge component for displaying status indicators, labels, and tags @@ -968,13 +1077,12 @@ noindex: true - Fixed outline blinking on image zoom modal open/close - External links now properly open in new tabs - Fixed dashboard design inconsistencies and improved spacing - - + ## Assistant improvements - - **Starter questions for assistant are here! You can add your own within the dashboard at [Assistant --> Settings](https://dashboard.mintlify.com/mintlify/mintlify/products/assistant/settings)** + - **Starter questions for assistant are here! You can add your own within the dashboard at [Assistant --\> Settings](https://app.mintlify.com/mintlify/mintlify/products/assistant/settings)** - Assistant insights quality has been improved with default spam protection for abusive keywords and JSON queries. ## API playground improvements @@ -1006,10 +1114,9 @@ noindex: true - Removed x-overflow in Palm theme that was cutting off text in the API playground. - Increased content font-size to improve compatibility with browser reader modes. - Fixed Google login button styling for better visual consistency. - - + ## Insights improvements - Improved insights page with fixed date selectors for "today" and "yesterday" @@ -1050,11 +1157,10 @@ noindex: true - Fixed page header text overflow with `break-all` styling - Removed full width constraint for page size options - Fixed button size for accept organization invitations - - Fixed keyboard shortcut display showing "Ctrl+I" without plus sign on non-macOS computers - + - Fixed keyboard shortcut display showing "Ctrl\+I" without plus sign on non-macOS computers - + ## Assistant and AI improvements - Upgraded assistant prompt for better accuracy and context-aware responses @@ -1092,13 +1198,12 @@ noindex: true - Fixed OG image display to show division name for index pages - Fixed icon paths to include `BASE_PATH` for relative paths - Fixed assistant background blur removal for better performance - - + ## Assistant and Agent AI features - - Added list_pull_requests and list_commits tools for agent such that it can document a date range of PRs or multiple PRs at once + - Added list\_pull\_requests and list\_commits tools for agent such that it can document a date range of PRs or multiple PRs at once - Upgraded agent and assistant to Claude Sonnet 4.5 - Improved assistant search to query docs in parallel for faster assistant responses - Fixed conversation length counting to exclude tool calls @@ -1137,7 +1242,7 @@ noindex: true - Fixed referrer tracking to use domain instead of full URL - Fixed images always becoming MDX block elements (kept inline images inline) - Removed comments in raw markdown pages such that you can use TODO comments without them leaking to users - - Fixed directory reading support for read_external_files + - Fixed directory reading support for read\_external\_files ## Component and styling @@ -1146,7 +1251,7 @@ noindex: true - Changed 404 page copy to be more clear - + ## New features - **Products navigation**: Organize documentation for multiple products with the product switcher navigation @@ -1187,7 +1292,7 @@ noindex: true - Improved PR publish state management in web editor - + ## Language support expansion - Added support for Romanian and Czech languages in the documentation interface @@ -1211,7 +1316,7 @@ noindex: true - Enhanced database schema updates for better user management - + ## Web editor and dashboard login improvements - Continued app router migration for the web editor, removing blockers and improving performance @@ -1231,7 +1336,7 @@ noindex: true - Fixed keyboard navigation in search and chat functionality - + ## Major releases - **Major enhancement**: AI suggested pages on 404 pages, [when someone hits a dead link → AI agent reads the path → suggests semantically similar pages](https://x.com/mintlify/status/1966625627773059495) @@ -1257,7 +1362,7 @@ noindex: true ## API playground and navigation - Multiple API playground response codes now display in a controlled styled select menu instead of the system default select menu when focused - - You can now use the [``expanded field on navigation groups in your docs.json to make them be default open``](https://mintlify.com/docs/navigation#default-expanded-state) + - You can now use the [`expanded field on navigation groups in your docs.json to make them be default open`](https://mintlify.com/docs/navigation#default-expanded-state) ## SEO and UI @@ -1273,7 +1378,7 @@ noindex: true - Assistant analytics exports are now executed in the background and sent via email for a more reliable experience - + ## Major release: Enhanced feedback collection - **Major improvement**: Readers can now give more detailed feedback after selecting _thumbs up/down_, including options and written comments. You can also collect feedback on code blocks and view all responses in your dashboard analytics.\ @@ -1305,7 +1410,7 @@ noindex: true - Performance improvement by moving the KaTeX CSS from cdnjs to our own CDN on Cloudfront for reduced latency - + ## Image handling improvements - **Major improvement**: Images no longer cause layout shift by default, even when width and height attributes aren't specified—automatic sizing prevents content jumping during page loads @@ -1331,11 +1436,11 @@ noindex: true ## Technical improvements and reliability - Enhanced logging system for update workflows enabling faster debugging and issue resolution - - Fixed GitHub rate limiting for customers with 10+ OpenAPI/AsyncAPI specs by switching from individual file fetching to repository cloning + - Fixed GitHub rate limiting for customers with 10\+ OpenAPI/AsyncAPI specs by switching from individual file fetching to repository cloning - Improved assistant reliability with backup LLM support, enhanced rate limit error handling, and more robust search tool functionality - + ## Performance and build optimizations - MDX transpilation now happens at deployment time instead of on every page load in uncached NextJS serverless environments, improving time to first byte for uncached pages. @@ -1380,7 +1485,7 @@ noindex: true - Fixed PDF render issues with certain page titles by sanitizing characters that cause generation problems - Resolved CLI error `Cannot convert undefined or null to object` when encountering empty OpenAPI JSON files - Fixed custom `docs.json` open-graph metatags being overwritten by generated ones - - Fixed RSS feed button clicks when landing on anchor links by using origin + pathname for RSS links + - Fixed RSS feed button clicks when landing on anchor links by using origin \+ pathname for RSS links - Improved CLI download speed by removing sourcemaps ## Technical improvements @@ -1390,7 +1495,7 @@ noindex: true - Comprehensive testing coverage for new features and edge cases - + ## Authentication improvements - Group-level public access: make entire page groups public via `docs.json` so you don’t need `public: true` on each page ([learn more](https://mintlify.com/docs/authentication-personalization/authentication-setup#group-level)) @@ -1404,7 +1509,7 @@ noindex: true - New [Search API endpoint](https://mintlify.com/docs/api-reference/assistant/search) so you can build agents and MCP servers on top of your docs - `openapi` and `asyncapi` files are now served at their specified paths (for example, `https://mydocsurl.extension/{openapi-or-file-name}.json`) - You can now use the [`x-mint field in your openapi files`](https://mintlify.com/docs/api-playground/openapi-setup#x-mint-extension) to override generated fields, customize preface content, or change endpoint URLs in code samples - - [``x-mcp is now x-mint.mcp``](https://mintlify.com/docs/api-playground/openapi-setup#mcp) in OpenAPI configurations to control which routes are exposed as MCP tools + - [`x-mcp is now x-mint.mcp`](https://mintlify.com/docs/api-playground/openapi-setup#mcp) in OpenAPI configurations to control which routes are exposed as MCP tools ## Assistant updates @@ -1431,7 +1536,7 @@ noindex: true - Internal DX improvements for enterprise customers with custom UI libraries—it's now easier for us to include your components and accommodate requests on shorter timelines - + ## Authentication improvements - Local development improvements to auth, enabling faster development of auth features and bug fixes in this product area @@ -1467,7 +1572,7 @@ noindex: true - Upgraded MongoDB from version 6 to 7 for improved performance and new features - + ## Slack app - Zero friction access: Bot responds to DMs, @mentions, and any question in your `#ask-ai` channel @@ -1489,7 +1594,7 @@ noindex: true - Added more customization options including focus mode, expandable code blocks, dark and light mode responsiveness, language dropdown menu, line numbering, and icons - + ## AI assistant updates - Improved accuracy through agentic RAG with tool calling @@ -1522,17 +1627,18 @@ noindex: true Can now use `mint update` to update your CLI. - + ## Web Editor 3.0 ![Webeditor3 Jpe](/images/webeditor3.jpeg) + Overhauled usability in the WYSIWYG editor. **Major improvements** - - Search for filenames using ⌘ + P shortcut + - Search for filenames using ⌘ \+ P shortcut - Pages load 10x faster - Faster load times when searching for a branch - Page options tab to configure layout, title, & metadata for SEO @@ -1554,6 +1660,7 @@ noindex: true ![AI Translations graphic](/images/changelog/translations.png) + Translate all of your documentation with AI. ## Export docs to PDF in beta @@ -1565,12 +1672,13 @@ noindex: true Bring interactivity to your docs. All standard React hooks are automatically available in your MDX files. [Learn more.](customize/react-components) - + ## MCP server generator ![screenshot of MCP server generator](/images/changelog/mcpgenerator.png) + Generate MCP servers so that AI applications can interact with your docs or APIs. Written content is automatically generated as an MCP server, and you can generate an MCP server from your OpenAPI spec with one click. Check out [docs on getting started with MCP.](/ai/model-context-protocol) ## Improvements @@ -1585,16 +1693,17 @@ noindex: true - Fixed icon style inconsistency for anchors without container - Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness - Show code examples even when in simple mode for API playground - - Support "command + k" shortcut for search in web editor + - Support "command \+ k" shortcut for search in web editor - Codeblocks within callouts expand to fill the width of the callout area - + ## New configuration schema `docs.json` ![docs.json screenshot](/images/changelog/docsjson.png) + We've introduced a new `docs.json` schema as a replacement for `mint.json`, to support better multi-level versioning, easier visual comprehension, and more consistent terminology. For more information on what's changed, [check out our blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json). Upgrade from `mint.json` to `docs.json` with the following steps: @@ -1626,6 +1735,7 @@ noindex: true ![graphic with text "Themes v2"](/images/changelog/themes.png) + New [pre-built themes](customize/themes) to modify the look & feel of your docs. Configure via your [docs.json file](organize/settings). Now available: @@ -1636,7 +1746,7 @@ noindex: true ## Other improvements - - [Guide to Technical Writing:](https://mintlify.com/guides/introduction)Best practices for writing technical documentation, including audience research, content types, and writing tips. + - [Guide to Technical Writing:](https://mintlify.com/guides/introduction) Best practices for writing technical documentation, including audience research, content types, and writing tips. - [Dropdown component](organize/navigation#dropdowns): Organize navigation with a dropdown, in addition to tabs and anchors. - [AI syntax fixer](https://x.com/ricardonunez_io/status/1892334887644123192): The web editor will catch if there’s a parsing error and use AI to suggest fixes. @@ -1672,6 +1782,7 @@ noindex: true ![Authentication screenshot](/images/changelog/authentication.png) + 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. @@ -1681,6 +1792,7 @@ noindex: true ![AI Assistant](/images/changelog/ai-assistant.jpg) + You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the writer will propose changes by generating a pull request. ## GitLab Integration Upgrade @@ -1692,6 +1804,7 @@ noindex: true ![Web Editor](/images/changelog/webeditor.jpg) + 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](/editor). @@ -1701,6 +1814,7 @@ noindex: true ![llms.txt support](/images/changelog/llms.jpg) + 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 @@ -1721,11 +1835,12 @@ noindex: true ![Changelog](/images/changelog/changelog.jpg) + ## 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,4,5} + ```javascript Line Highlighting Example highlight={1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); @@ -1758,6 +1873,7 @@ noindex: true ![Advanced Footer](/images/changelog/advanced-footer.gif) + 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 @@ -1798,6 +1914,7 @@ noindex: true ![Custom Fonts](/images/changelog/custom-fonts.jpeg) + 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 @@ -1809,6 +1926,7 @@ noindex: true ![Performance Improvements](/images/changelog/performance-improvements.png) + 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 @@ -1816,6 +1934,7 @@ noindex: true ![SEO Improvements](/images/changelog/seo-improvements.jpeg) + 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 @@ -1870,6 +1989,7 @@ noindex: true ![AI Widget](/images/changelog/widget.png) + 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) diff --git a/cli/commands.mdx b/cli/commands.mdx index deb5b256c0..57c691431f 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -2,6 +2,7 @@ title: "Commands" description: "Complete reference for every Mintlify CLI command and flag, including mint dev, mint build, mint validate, mint analytics, and more." keywords: ["CLI", "mint", "commands", "flags", "reference"] +boost: 3 --- ## Global flags @@ -167,6 +168,102 @@ mint analytics conversation buckets view --- +## `mint workflow` + +Create, list, and delete [workflows](/workflows) from the terminal. Requires authentication with `mint login`. + +```bash +mint workflow [flags] +``` + +All subcommands accept these shared flags: + +| Flag | Description | +| --- | --- | +| `--subdomain` | Documentation subdomain. Defaults to the value set with `mint config set subdomain`, or the first project on your account. | +| `--format` | Output format: `table` (default, pretty) or `json` (raw, machine-readable). | + +When `--format json` is set, errors print to stderr as `Error: ` and the command exits with a non-zero status, so you can pipe successful output into other tools. + +### `mint workflow create` + +Create a new workflow. You can pass the workflow definition inline with flags, or point at a JSON or YAML file with `--file`. + +```bash +mint workflow create [flags] +``` + +| Flag | Description | +| --- | --- | +| `--name` | Workflow name. Required unless `--file` is provided. | +| `--prompt` | Instructions appended to the workflow's base prompt on every run. | +| `--type` | Workflow type. One of `changelog`, `source-code-agent`, `translations`, `writing-style`, `typo-check`, `broken-link-detection`, `seo-metadata-audit`, `assistant-docs-updates`, or `contextual-feedback-docs-updates`. Omit for a custom workflow. | +| `--cron` | Cron expression for a scheduled trigger. Mutually exclusive with `--push-repo`. | +| `--push-repo` | Repository (`owner/repo`) for a push trigger. Repeatable to listen to multiple repositories. Mutually exclusive with `--cron`. | +| `--context-repo` | Additional context repository (`owner/repo`) the agent reads when the workflow runs. Repeatable, up to 10 total. | +| `--automerge` | Automatically merge pull requests opened by this workflow. See [Configure automerge](/guides/configure-automerge) for setup requirements. | +| `--file` | Path to a JSON or YAML file containing the full workflow body. Overrides the inline flags. | + +Exactly one trigger is required: pass `--cron` for a scheduled workflow or one or more `--push-repo` flags for a push-triggered workflow. + +#### Examples + +```bash +# Scheduled translations workflow +mint workflow create \ + --name "Translate content" \ + --type translations \ + --cron "0 6 * * *" + +# Push-triggered workflow with extra context +mint workflow create \ + --name "Sync API reference" \ + --type source-code-agent \ + --push-repo my-org/api \ + --context-repo my-org/shared-types \ + --automerge + +# Create from a file +mint workflow create --file workflow.yaml +``` + +A workflow file uses the same shape as the inline flags. The `on` field holds the trigger: + +```yaml +name: Translate content +type: translations +on: + cron: "0 6 * * *" +prompt: Prefer formal tone in French translations. +automerge: false +context: + - repo: my-org/shared-content +``` + +### `mint workflow list` + +List workflows for the current deployment. + +```bash +mint workflow list [flags] +``` + +The default table output shows each workflow's ID, name, type, trigger, and status. Use `--format json` to get the full workflow objects. + +### `mint workflow delete` + +Delete a workflow by ID. Use `mint workflow list` to get the ID. + +```bash +mint workflow delete [flags] +``` + +| Argument | Description | +| --- | --- | +| `id` | Workflow schema ID to delete. | + +--- + ## `mint config` Manage persistent default values for CLI commands. The configuration saves in `~/.config/mintlify/config.json`. @@ -185,7 +282,7 @@ mint config [value] | Key | Description | Used by | | --- | --- | --- | -| `subdomain` | Default documentation subdomain. | `mint analytics` | +| `subdomain` | Default documentation subdomain. | `mint analytics`, `mint workflow` | | `dateFrom` | Default start date for analytics queries (`YYYY-MM-DD`). | `mint analytics` | | `dateTo` | Default end date for analytics queries (`YYYY-MM-DD`). | `mint analytics` | diff --git a/cli/install.mdx b/cli/install.mdx index 5da3391474..eddd9f0ff6 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -79,7 +79,7 @@ If `mint update` is not available on your version, reinstall the CLI with the la ## Formatting -For syntax highlighting and code formatting in MDX files, we recommend using the following extensions: +For syntax highlighting and code formatting in MDX files, use the following extensions: - **Cursor, Windsurf, VS Code**: [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm) diff --git a/components/accordions.mdx b/components/accordions.mdx index 80614d05fd..5f0254137d 100644 --- a/components/accordions.mdx +++ b/components/accordions.mdx @@ -2,13 +2,14 @@ title: "Accordions" description: "Use the accordion component to show and hide content sections, organize related information, and enable progressive disclosure in your docs." keywords: ["accordions", "collapsible content", "expandable sections", "progressive disclosure"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; Accordions allow users to expand and collapse content sections. Use accordions for progressive disclosure and to organize information. -When you open an accordion, the URL hash updates, which allows you to share direct links to specific accordion sections. +When you open an accordion, the URL hash updates, which lets you share direct links to specific accordion sections. ## Single accordion diff --git a/components/badge.mdx b/components/badge.mdx index e51d2c619a..e61b948ba3 100644 --- a/components/badge.mdx +++ b/components/badge.mdx @@ -2,6 +2,7 @@ title: "Badge" description: "Use the badge component to highlight status indicators, version labels, or metadata inline with customizable colors and hover tooltips." keywords: ["badge", "label", "tag", "status", "indicator"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/banner.mdx b/components/banner.mdx index 94182636b7..b580a08458 100644 --- a/components/banner.mdx +++ b/components/banner.mdx @@ -2,6 +2,7 @@ title: "Banner" description: "Add a dismissible banner at the top of your documentation site to display important announcements, release notes, or notifications." keywords: ["banner", "announcements", "site-wide"] +boost: 3 --- Use banners to display important announcements, updates, or notifications across your entire documentation site. Banners appear at the top of every page, support Markdown formatting, and you can make them dismissible. By default, banners use the color defined by the `colors.dark` property in your `docs.json`. You can change the appearance with the `type` property or override the background entirely with `color`. diff --git a/components/callouts.mdx b/components/callouts.mdx index 78c6065f44..615174d4d5 100644 --- a/components/callouts.mdx +++ b/components/callouts.mdx @@ -2,6 +2,7 @@ title: "Callouts" description: "Add info, notes, tips, checks, warnings, danger, and custom callout components to highlight important information in your documentation." keywords: ["callouts", "notes", "warnings", "info boxes", "tips", "emphasis", "highlight"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/cards.mdx b/components/cards.mdx index 804355e98b..f9d173771f 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -2,6 +2,7 @@ title: "Cards" description: "Use the Mintlify Card component to display links, icons, images, and grouped content as visual containers, including horizontal layouts and CardGroup grids." keywords: ["cards", "visual containers"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/color.mdx b/components/color.mdx index 2d693fb2e3..b85eaa3698 100644 --- a/components/color.mdx +++ b/components/color.mdx @@ -2,6 +2,7 @@ title: "Color" description: "Display color swatches with hex values and click-to-copy capability using the color component for design system and branding documentation." keywords: ["color", "palette", "colors", "design system", "hex", "rgb", "rgba", "hsl", "oklch"] +boost: 3 --- Use the Color component to showcase color palettes in your documentation. Display colors in a compact grid or organize them in a table with labeled rows. diff --git a/components/columns.mdx b/components/columns.mdx index ef87e7ffac..6afc0c61c5 100644 --- a/components/columns.mdx +++ b/components/columns.mdx @@ -2,6 +2,7 @@ title: 'Columns' description: "Arrange cards and other components in a responsive multi-column grid layout with the columns component, including customizable column counts." keywords: ['card groups', 'grid layout', 'multi-column layout'] +boost: 3 --- The `Columns` component lets you arrange content in a responsive grid layout. It's most often used to put cards in a grid, by specifying the number of grid columns. You can also use the `Column` sub-component to wrap arbitrary content. Columns are responsive and automatically adjust for smaller screens. diff --git a/components/examples.mdx b/components/examples.mdx index 948e8b37d7..6dfcbe7180 100644 --- a/components/examples.mdx +++ b/components/examples.mdx @@ -2,6 +2,7 @@ title: "Examples" description: "Display code examples in the right sidebar panel on desktop devices to show request and response samples alongside API documentation." keywords: ["RequestExample", "ResponseExample", "code examples", "request-response"] +boost: 3 --- The `` and `` components display code blocks in the right sidebar to create a two-column layout that keeps examples visible while users scroll through your content. Use these components for API documentation, but they work on all pages. diff --git a/components/expandables.mdx b/components/expandables.mdx index e9065f6bd3..ef20314608 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -2,6 +2,7 @@ title: "Expandables" description: "Use the expandable component to toggle nested object properties in API documentation, showing child fields for request and response objects." keywords: ["expandables", "nested properties", "expandable fields", "toggle content"] +boost: 3 --- Use expandables to show and hide nested content within response fields. They are particularly useful for displaying complex object properties in API documentation. diff --git a/components/fields.mdx b/components/fields.mdx index fe53ea0eda..4c323fa35d 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -2,6 +2,7 @@ title: "Fields" description: "Use ParamField and ResponseField components to document API request and response parameters with types, defaults, and validation rules." keywords: ["ParamField", "ResponseField", "request parameters", "response documentation"] +boost: 3 --- Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields. diff --git a/components/frames.mdx b/components/frames.mdx index 7c903be3d7..d0473eba52 100644 --- a/components/frames.mdx +++ b/components/frames.mdx @@ -2,6 +2,7 @@ title: "Frames" description: "Wrap images, videos, and other components with the frame component to add styled borders, captions, and visual emphasis to your content." keywords: ["image frames", "visual emphasis", "captions", "border"] +boost: 3 --- Use frames to display images, diagrams, videos, or other visual content with consistent styling and optional captions. Frames center content and provide visual separation from surrounding text. @@ -20,7 +21,7 @@ Add additional context to an image using the optional `caption` prop. Captions a ### Markdown in captions -Captions support markdown formatting, including links and bold text. +Captions support Markdown formatting, including links and bold text. Photograph of Yosemite Valley. @@ -32,7 +33,7 @@ Captions support markdown formatting, including links and bold text. ## Hints -Add text that precedes the frame using the optional `hint` prop. Hints appear above the frame. +Add text that precedes the frame using the optional `hint` prop. Hints appear before the frame. Photograph of a lake surrounded by trees with mountains in the distance in Yellowstone National Park. @@ -53,7 +54,7 @@ Videos without `autoPlay` do not have any additional attributes added by default ## Properties - Text that appears as part of the frame, centered below the content. Supports markdown formatting including links and bold text. + Text that appears as part of the frame, centered below the content. Supports Markdown formatting including links and bold text. diff --git a/components/icons.mdx b/components/icons.mdx index fb6b764e30..9421adb1eb 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -2,6 +2,7 @@ title: "Icons" description: "Add icons from Font Awesome, Lucide, Tabler, or custom sources to your documentation pages using the icon component with size and color options." keywords: ["Font Awesome", "Lucide", "Tabler", "SVGs"] +boost: 3 --- import IconsRequired from "/snippets/icons-required.mdx"; @@ -16,10 +17,10 @@ Use icons from Font Awesome, Lucide, Tabler, SVGs, external URLs, or files in yo ## Inline icons -Icons are placed inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis. +Icons appear inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis. ```markdown Inline icon example -Icons are placed inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis. +Icons appear inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis. ``` ## Properties diff --git a/components/index.mdx b/components/index.mdx index b54daa1743..f01d7b6274 100644 --- a/components/index.mdx +++ b/components/index.mdx @@ -1,8 +1,9 @@ --- -title: "Overview" +title: "Components overview" description: "Browse the full Mintlify component library for layout, emphasis, API documentation, and navigation elements available in your MDX pages." keywords: ["MDX components", "documentation components", "UI components", "components"] +boost: 3 --- Mintlify provides built-in MDX components for your documentation pages. Use these components to structure content, draw attention to important information, document APIs, and guide navigation. diff --git a/components/mermaid-diagrams.mdx b/components/mermaid-diagrams.mdx index 922d7084d1..81913aea18 100644 --- a/components/mermaid-diagrams.mdx +++ b/components/mermaid-diagrams.mdx @@ -2,6 +2,7 @@ title: "Mermaid" description: "Create flowcharts, sequence diagrams, and other visualizations in your documentation using Mermaid syntax with automatic rendering." keywords: ["Mermaid", "flowcharts", "diagrams"] +boost: 3 --- [Mermaid](https://mermaid.js.org/) lets you build flowcharts, sequence diagrams, Gantt charts, and other diagrams using text and code. diff --git a/components/panel.mdx b/components/panel.mdx index 1867bffe37..efb8e89391 100644 --- a/components/panel.mdx +++ b/components/panel.mdx @@ -2,6 +2,7 @@ title: "Panel" description: "Customize the right side panel content on documentation pages to display supplementary information, examples, or navigation elements." keywords: ["sidebar"] +boost: 3 --- You can use the `` component to customize the right side panel of a page with any components that you want. diff --git a/components/prompt.mdx b/components/prompt.mdx index f6796e1754..2455816d53 100644 --- a/components/prompt.mdx +++ b/components/prompt.mdx @@ -2,6 +2,7 @@ title: "Prompt" description: "Display pre-built AI prompts with one-click copy and Cursor integration buttons so users can quickly use prompts in their AI tools." keywords: ["prompt", "AI", "cursor", "copy", "prompt card"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/steps.mdx b/components/steps.mdx index 0a3c337939..a2d74ebb6b 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -2,6 +2,7 @@ title: "Steps" description: "Create numbered step-by-step procedures with the steps component to guide users through sequential tasks, tutorials, and setup workflows." keywords: ["sequence", "numbered steps", "procedures", "tutorial steps"] +boost: 3 --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/tabs.mdx b/components/tabs.mdx index 46d9c03aa0..634d3054e0 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -2,6 +2,7 @@ title: "Tabs" description: "Use the tab component to organize content into switchable panels for showing different options, platform versions, or language examples." keywords: ["tabbed content", "content panels", "switchable content"] +boost: 3 --- Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. diff --git a/components/tiles.mdx b/components/tiles.mdx index 5a91e383d5..a7d02920bd 100644 --- a/components/tiles.mdx +++ b/components/tiles.mdx @@ -2,6 +2,7 @@ title: "Tiles" description: "Use the tiles component to display visual previews with image thumbnails, titles, and descriptions in a responsive grid layout for your docs." keywords: ["tiles", "visual preview", "grid", "showcase"] +boost: 3 --- Use tiles to create visual showcase elements with a patterned background, title, and description. Tiles are ideal for displaying component previews, feature highlights, or navigation items in a grid layout. @@ -57,7 +58,7 @@ Combine tiles with the [columns component](/components/columns) to create a resp ## Properties - URL to navigate to when the tile is clicked. + URL to navigate to when users click the tile. diff --git a/components/tooltips.mdx b/components/tooltips.mdx index 00d23df59d..3be3dedd50 100644 --- a/components/tooltips.mdx +++ b/components/tooltips.mdx @@ -2,6 +2,7 @@ title: "Tooltips" description: "Add tooltips to display contextual definitions and explanations when users hover over terms, abbreviations, or technical concepts in your documentation." keywords: ["tooltips", "hover help", "contextual information", "explanatory", "definitions"] +boost: 3 --- Use tooltips to provide additional context or definitions when a user hovers over a string of text. Tooltips can include optional call-to-action links. diff --git a/components/tree.mdx b/components/tree.mdx index ef9162bfb4..7cd86a18c9 100644 --- a/components/tree.mdx +++ b/components/tree.mdx @@ -2,6 +2,7 @@ title: "Tree" description: "Use the tree component to display hierarchical file and folder structures with collapsible nodes and syntax highlighting for path names." keywords: ["tree", "file tree", "folder structure", "hierarchical navigation", "file system"] +boost: 3 --- Use tree components to display hierarchical structures like file systems, project directories, or nested content. The tree component supports keyboard navigation and accessibility features. diff --git a/components/update.mdx b/components/update.mdx index 1c0ca3e9b5..57d13e14a0 100644 --- a/components/update.mdx +++ b/components/update.mdx @@ -2,6 +2,7 @@ title: "Update" description: "Use the update component to display product updates, release notes, and changelog entries in a structured timeline format with dates." keywords: ["changelogs", "product updates", "release notes"] +boost: 3 --- Use the `Update` component to display changelog entries, version updates, and release notes with consistent formatting. diff --git a/components/view.mdx b/components/view.mdx index 4c4969bdf0..4eb57ea86d 100644 --- a/components/view.mdx +++ b/components/view.mdx @@ -2,6 +2,7 @@ title: "View" description: "Use the view component to create switchable content panels for different programming languages, frameworks, or configuration alternatives." keywords: ["selector", "language-specific content", "content switching"] +boost: 3 --- Use the `View` component to create content that changes based on the selected view in a multi-view dropdown. This is particularly useful for showing code examples or documentation specific to different programming languages or frameworks. @@ -11,7 +12,7 @@ Use the `View` component to create content that changes based on the selected vi - This content is only visible when JavaScript is selected. + This content only appears when you select JavaScript. ```javascript console.log("Hello from JavaScript!"); @@ -19,7 +20,7 @@ Use the `View` component to create content that changes based on the selected vi - This content is only visible when Python is selected. + This content only appears when you select Python. ```python print("Hello from Python!") @@ -30,7 +31,7 @@ Use the `View` component to create content that changes based on the selected vi ````mdx JavaScript and Python views - This content is only visible when JavaScript is selected. + This content only appears when you select JavaScript. ```javascript console.log("Hello from JavaScript!"); @@ -38,7 +39,7 @@ Use the `View` component to create content that changes based on the selected vi - This content is only visible when Python is selected. + This content only appears when you select Python. ```python print("Hello from Python!") diff --git a/components/visibility.mdx b/components/visibility.mdx index a01e445a9f..84964fdedf 100644 --- a/components/visibility.mdx +++ b/components/visibility.mdx @@ -2,6 +2,7 @@ title: "Visibility" description: "Use the visibility component to show different content to humans on the web UI and to AI agents in Markdown output for conditional rendering." keywords: ["visibility", "agents", "humans", "markdown", "AI", "conditional content"] +boost: 3 --- Use the `Visibility` component to show different content to humans reading your site versus AI agents processing the Markdown output. This lets you customize information for each audience without maintaining separate pages. @@ -24,7 +25,7 @@ On your published site, content marked `for="humans"` renders normally and conte - > You are viewing this content **in markdown**. + > You are viewing this content **in Markdown**. > > This content only appears on the Markdown version of pages. > @@ -47,7 +48,7 @@ On your published site, content marked `for="humans"` renders normally and conte - > You are viewing this content **in markdown**. + > You are viewing this content **in Markdown**. > > This content only appears on the Markdown version of pages. > diff --git a/contact-support.mdx b/contact-support.mdx index 614b7646b3..71563eb96d 100644 --- a/contact-support.mdx +++ b/contact-support.mdx @@ -13,7 +13,7 @@ Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tut ## Message support -Send us a message from your [dashboard](https://dashboard.mintlify.com/). Select **Support** in the sidebar. +Send us a message from your [dashboard](https://app.mintlify.com/). Click **Support** in the sidebar. Contact support panel open in the dashboard. @@ -26,4 +26,4 @@ Send us a message from your [dashboard](https://dashboard.mintlify.com/). Select ## Contact via email -If you can't access your dashboard, please email us at support@mintlify.com. Please include the URL of your [dashboard](https://dashboard.mintlify.com/) with your organization and deployment in your email so we can help you faster. For example, `dashboard.mintlify.com/your-org/your-deployment`. +If you can't access your dashboard, email us at support@mintlify.com. Include the URL of your [dashboard](https://app.mintlify.com/) with your organization and deployment in your email so we can help you faster. For example, `app.mintlify.com/your-org/your-deployment`. diff --git a/create/changelogs.mdx b/create/changelogs.mdx index 02d98dfad2..869467858e 100644 --- a/create/changelogs.mdx +++ b/create/changelogs.mdx @@ -2,13 +2,14 @@ title: "Changelogs" description: "Create product changelogs with date-based entries, RSS feed support, and subscriber notifications to keep users informed about updates." keywords: ["product updates", "release notes", "RSS"] +boost: 3 --- Create a changelog for your docs by adding [Update components](/components/update) to a page. Check out the [Mintlify changelog](/changelog) as an example: you can include links, images, text, and demos of your new features in each update. -## Setting up your changelog +## Set up your changelog @@ -38,7 +39,7 @@ description: "Product updates and announcements" ``` -## Customizing your changelog +## Customize your changelog Control how people navigate your changelog and stay up to date with your product information. @@ -61,7 +62,9 @@ Each `label` property for an `Update` automatically creates an entry in the righ ### Tag filters -Add `tags` to your `Update` components to replace the table of contents with tag filters. Users can filter the changelog by selecting one or more tags: +Add `tags` to your `Update` components to replace the table of contents with tag filters. Users can filter the changelog by selecting one or more tags. + +When a user selects multiple tags, the changelog shows only updates that include every selected tag. Updates without any tags are hidden whenever a filter is active. ```mdx Tag filters example wrap diff --git a/create/code.mdx b/create/code.mdx index a9a8fabe17..db8fc24dd1 100644 --- a/create/code.mdx +++ b/create/code.mdx @@ -4,7 +4,7 @@ description: "Format code in your documentation with syntax highlighting, line n keywords: ["code blocks", "syntax highlighting", "code styling"] --- -## Adding code samples +## Add code samples You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more. @@ -18,7 +18,7 @@ To denote a `word` or `phrase` as code, enclose it in backticks (`). ### Code blocks -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Code blocks are copyable, and if you have the assistant enabled, users can ask AI to explain the code. +Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Code blocks are copyable, and if you have the assistant enabled, users can ask the assistant to explain the code. Specify the programming language for syntax highlighting and to enable meta options. Add any meta options, like a title or icon, after the language. diff --git a/create/files.mdx b/create/files.mdx index 0aa83502ad..660744f54e 100644 --- a/create/files.mdx +++ b/create/files.mdx @@ -2,6 +2,7 @@ title: "Files" description: "Serve static assets like images, videos, PDFs, and data files from your documentation repository with automatic optimization and CDN delivery." keywords: ["static assets","supported file types"] +boost: 3 --- Mintlify automatically serves static assets from your documentation repository at the appropriate path on your domain. For example, if you have `/images/my-logo.png` in your repo, the image file is available at `https://docs.your-project.com/images/my-logo.png`. @@ -22,7 +23,7 @@ Supported file types for all plans: - **Video**: `.mp4`, `.webm` - **Audio**: `.mp3`, `.wav` - **Data**: `.json`, `.yaml` -- **Stylesheets**: `.css` +- **Stylesheet**: `.css` - **Scripts**: `.js` - **Fonts**: `.woff`, `.woff2`, `.ttf`, `.eot` diff --git a/create/redirects.mdx b/create/redirects.mdx index 40c145bc09..b9254ac494 100644 --- a/create/redirects.mdx +++ b/create/redirects.mdx @@ -2,6 +2,7 @@ title: "Redirects" description: "Configure URL redirects in docs.json for moved, renamed, or deleted documentation pages to preserve SEO rankings and prevent broken links." keywords: ["redirects"] +boost: 3 --- When you change the path of a file in your docs folder, it also changes the URL path to that page. This may happen when restructuring your docs or changing the sidebar title. diff --git a/create/reusable-snippets.mdx b/create/reusable-snippets.mdx index 42422d90b8..f3c5e93946 100644 --- a/create/reusable-snippets.mdx +++ b/create/reusable-snippets.mdx @@ -121,6 +121,24 @@ Use variables to pass data to a snippet when you import it. ``` +Variables also interpolate inside fenced code blocks. This is useful for snippets that include installation commands or other code examples that differ by package name, version, or environment. + +````mdx shared/install-snippet.mdx +export const InstallSnippet = ({ packageName }) => <>; + +Install the package: + +```bash +npm install {packageName} +``` +```` + +```mdx destination-file.mdx +import InstallSnippet from "/shared/install-snippet.mdx"; + + +``` + ### Import React components 1. Create a snippet with a JSX component. See [React components](/customize/react-components) for more information. diff --git a/create/text.mdx b/create/text.mdx index cb5f714616..04d4dba9bd 100644 --- a/create/text.mdx +++ b/create/text.mdx @@ -8,7 +8,7 @@ keywords: ["Markdown formatting", "text styling", "headers", "anchor links", "cu Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation. -### Creating headers +### Create headers Use `#` symbols to create headers of different levels: @@ -36,7 +36,7 @@ The custom ID replaces the auto-generated anchor, so you can link to the heading This is useful when you want stable anchor links that don't change if you update the heading text, or when you need shorter, more memorable anchors. -### Disabling anchor links +### Disable anchor links By default, headers include clickable anchor links that allow users to link directly to specific sections. You can disable these anchor links using the `noAnchor` prop in HTML or React headers. @@ -72,7 +72,7 @@ Apply these formatting styles to your text: | *Italic* | `_text_` | `_emphasis_` | *emphasis* | | ~~Strikethrough~~ | `~text~` | `~deprecated feature~` | ~~deprecated feature~~ | -### Combining formats +### Combine formats You can combine formatting styles: @@ -250,6 +250,23 @@ Content following the rule. Use horizontal rules sparingly. In most cases, headers provide better content separation with the added benefit of navigation anchors. +## Comments + +Use MDX-style comments to add notes, reminders, or to-dos in your source files. Comments don't render in the published page. + +```mdx +{/* This is a comment and won't appear in the published docs. */} + +{/* + Multi-line comments work too. + Useful for TODOs or reviewer notes. +*/} +``` + + + HTML-style `` comments are not supported in MDX. Always use `{/* ... */}`. + + ## Best practices ### Content organization diff --git a/credits.mdx b/credits.mdx new file mode 100644 index 0000000000..860261af87 --- /dev/null +++ b/credits.mdx @@ -0,0 +1,79 @@ +--- +title: "Credit pricing" +description: "Understand how Mintlify credits work for assistant messages, agent runs, and workflows. How credit tiers, overages, and rollovers are billed." +keywords: ["credits", "billing", "pricing", "AI chat", "messages", "tiers", "usage"] +--- + +Some Mintlify features consume credits. + +* Assistant responses +* Agent runs in the editor or on Slack +* Workflow runs + +For the most current pricing information, see the [Pricing page](https://mintlify.com/pricing) or view the [Usage](https://app.mintlify.com/settings/organization/usage) page in your dashboard. + +## Pricing tiers + +| Monthly credits | Monthly cost | Rollover cap | +|:----------------|:-------------|:-------------| +| 0 | $0 | 0 | +| 10,250 | $100 | 15,375 | +| 26,000 | $250 | 39,000 | +| 52,500 | $500 | 78,750 | +| 80,000 | $750 | 120,000 | +| 108,500 | $1,000 | 162,750 | +| 275,000 | $2,500 | 412,500 | +| 555,000 | $5,000 | 832,500 | +| 850,000 | $7,500 | 1,275,000 | +| 1,150,000 | $10,000 | 1,725,000 | + +**Overages** are charged per additional credit at $0.01 rather than triggering an automatic tier upgrade. You can set usage alerts to receive an email when you reach a certain percentage of your tier limit. Allowing overages can be cheaper than moving up a tier depending on your usage patterns. + + + Overages are disabled by default. You must enable them on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. + + +**Rollovers** carry forward up to 50% of unused credits to the next month, so the maximum credits available in any month is 1.5 times your monthly limit. Rollovers reset if you change tiers. + +Higher tiers offer a lower effective cost per credit. If your usage consistently reaches the top of your current tier, upgrading is more economical than paying ongoing overage charges. + +Upgrades and downgrades take effect immediately and are prorated for the current billing cycle. + +For high-volume usage or custom credit packages, [contact sales](mailto:sales@mintlify.com). Custom credit packages are available on enterprise plans only. + +## How credits work + +Different features consume different amounts of credits per interaction: + +| Feature | Average credits per interaction | +|:--------|:--------------------------------| +| Assistant response | 23 | +| Editor agent run | 115 | +| Slack agent run | 110 | + +Workflows also consume credits when they run: + +| Workflow | Average credits per run | +|:---------|:------------------------| +| Update from code changes | 180 | +| Update from assistant conversations | 212 | +| Broken link detection | 285 | +| Changelog | 223 | +| SEO audit | 422 | +| Translations | 913 | +| Typo check | 330 | +| Writing style | 235 | + +## Estimating your usage + +Use the averages in the [How credits work](#how-credits-work) section to estimate your monthly credit needs. + +For example, if your docs site handles 500 assistant responses per month, that's roughly 11,500 credits (500 × 23). Adding a weekly broken link detection workflow adds about 1,140 credits per month (4 × 285). + +After using credit-powered features for a month, review your usage patterns to see if you should adjust your tier. + +## Cost optimization + +**Schedule workflows instead of triggering on every push.** Workflows like SEO audits, writing style checks, and broken link detection don't need to run on every code change. Running these on a daily or weekly cron schedule rather than on every push significantly reduces credit consumption without meaningful impact on content quality. + +**Monitor your usage patterns.** The [Usage](https://app.mintlify.com/settings/organization/usage) page in your dashboard shows a breakdown by feature category. If a particular workflow is consuming more credits than expected, review its trigger or any custom instructions. diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index 1a777548d2..d54a840379 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -15,7 +15,7 @@ To host your documentation on a custom domain: ## Add your custom domain -1. Navigate to the [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard. +1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. 2. Enter your domain name. For example, `docs.example.com` or `www.example.com`. 3. Click **Add domain**. @@ -46,18 +46,33 @@ CNAME | docs | cname.mintlify.builders - If you migrate an existing domain and want zero downtime, add the verification `TXT` records before updating your `CNAME`. Then wait until SSL/TLS certificates pre-provision before cutting over. Switching the `CNAME` before certificates are issued causes HTTPS requests to fail until provisioning completes. + Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes. + + If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify. +### Verification TXT records + +After you add a custom domain, the dashboard displays two `TXT` records that you must add at your DNS provider: + +```text +TXT | _acme-challenge. | +TXT | _cf-custom-hostname. | +``` + +The `_acme-challenge` record authorizes Let's Encrypt to issue a TLS certificate for your domain, and the `_cf-custom-hostname` record verifies that you control the domain. + +The dashboard polls DNS in the background and marks each record with a green check once it verifies the expected value. After saving records at your DNS provider, allow a short time for propagation before status updates appear. + ### DNS propagation -DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. You can verify your DNS is configured correctly using [DNSChecker](https://dnschecker.org). +DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. Use a tool like [DNSChecker](https://dnschecker.org) to verify your DNS configuration is correct. -Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Vercel provisions your TLS certificate. +Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Mintlify provisions your TLS certificate. ### Automatic TLS provisioning -Once your DNS records propagate and resolve correctly, Vercel automatically provisions a free SSL/TLS certificate for your domain using Let's Encrypt. +After you add your `TXT` records and your DNS records resolve correctly, Mintlify generates a free SSL/TLS certificate for your site using Let's Encrypt. This typically completes within a few hours of DNS propagation, though it can take up to 24 hours in rare cases. Certificates are automatically renewed before expiration. @@ -71,19 +86,23 @@ If your domain uses CAA (Certification Authority Authorization) records, you mus ### Reserved paths -The `/.well-known/acme-challenge` path is reserved for certificate validation and cannot be redirected or rewritten. If you have configured redirects or rewrites for this path, certificate provisioning fails. +Mintlify reserves the `/.well-known/acme-challenge` path for certificate validation. You cannot redirect or rewrite this path. If you have configured redirects or rewrites for this path, certificate provisioning fails. ### Provider-specific settings - - - If Vercel is your domain provider, you must add a verification `TXT` record. This information appears on your dashboard after submitting your custom domain, and is emailed to you. - + + If Cloudflare is your DNS provider, you must enable the "Full (strict)" mode for the SSL/TLS encryption setting. Additionally, disable "Always Use HTTPS" in your Edge Certificates settings. Cloudflare's HTTPS redirect blocks Let's Encrypt from validating your domain during certificate provisioning. + + +### Retry validation + +If your domain is still pending validation after adding the verification `TXT` record, you can retry validation manually from your dashboard. + +1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. +2. Find your pending custom domain. +3. Click **Retry validation**. - - If Cloudflare is your DNS provider, you must enable the "Full (strict)" mode for the SSL/TLS encryption setting. Additionally, disable "Always Use HTTPS" in your Edge Certificates settings. Cloudflare's HTTPS redirect blocks Let's Encrypt from validating your domain during certificate provisioning. - - +Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation. ## Set a canonical URL diff --git a/customize/custom-scripts.mdx b/customize/custom-scripts.mdx index c475b449ab..a7139c5762 100644 --- a/customize/custom-scripts.mdx +++ b/customize/custom-scripts.mdx @@ -104,7 +104,7 @@ Each ID appears once per page. Use these as `#value` in CSS. For example, `#navb - `#endpoints-menu-trigger` — Button that opens the endpoint selector dropdown. - - `#ask-ai-code-block-button` — "Ask AI" button that appears on code blocks. + - `#ask-assistant-code-block-button` — "Ask Assistant" button that appears on code blocks. - `#code-snippet-feedback-button` — Feedback button on code snippets. - `#code-snippet-feedback-textarea` — Text area within the code snippet feedback form. @@ -345,7 +345,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` ## Custom JavaScript -Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `