From 533a6477dcfd091cbf3ffb3ae2812f6e48b30d8a Mon Sep 17 00:00:00 2001 From: Denzell <32852291+cdxker@users.noreply.github.com> Date: Mon, 6 Jul 2026 17:45:28 -0700 Subject: [PATCH] Updated mintlify pages - Updated cli/install.mdx - Updated optimize/search.mdx - Updated ai/mintlify-mcp.mdx - Updated organize/navigation.mdx - Updated cli/commands.mdx - Updated organize/pages.mdx - Updated organize/hidden-pages.mdx - Updated .vale.ini - Updated ai/llmstxt.mdx - Updated credits.mdx - Updated optimize/analytics.mdx - Updated ai-native.mdx - Updated customize/fonts.mdx - Updated customize/custom-scripts.mdx - Updated quickstart.mdx Mintlify-Source: dashboard-editor --- .vale.ini | 31 ++++- ai-native.mdx | 11 +- ai/llmstxt.mdx | 4 +- ai/mintlify-mcp.mdx | 241 ++++++++++++++++++++++++++++++++--- cli/commands.mdx | 4 +- cli/install.mdx | 45 ++++--- credits.mdx | 43 +++++-- customize/custom-scripts.mdx | 188 ++++++++++++++++----------- customize/fonts.mdx | 72 ++++++----- optimize/analytics.mdx | 39 +++--- optimize/search.mdx | 4 +- organize/hidden-pages.mdx | 10 +- organize/navigation.mdx | 103 ++++++++------- organize/pages.mdx | 11 +- quickstart.mdx | 5 +- 15 files changed, 563 insertions(+), 248 deletions(-) diff --git a/.vale.ini b/.vale.ini index 3df30982e..dd31a5033 100644 --- a/.vale.ini +++ b/.vale.ini @@ -2,7 +2,7 @@ StylesPath = .vale/styles MinAlertLevel = suggestion -IgnoredScopes = code, tt, img, url, a +IgnoredScopes = code, code, tt, img, url, a SkippedScopes = script, style, pre, figure, code Vocab = Mintlify @@ -20,17 +20,22 @@ TokenIgnores = (?m)((?:import|export) .+?$), \ (?)(?!`), \ (<[A-Z]\w+>.+?<\/[A-Z]\w+>), \ (<[^>]*>), \ -\{(?!/\*)[^}]*\}, \ -(`[^`]*`), \ -(?m)^openapi: .+$, \ +\{(?!/\*)(?!/\*)[^}]*\}, \ +(`[^`]*`), \, \ +(?m)^openapi: .+$, \(?m)^openapi: .+$, \ +([\w-]+\.)+(?:json|jsonl|png|jpe?g|gif|svg|mdx?|txt|ya?ml|xml|com|dev|io|ts|js|tsx|jsx), \ +[\w-]+="[^"\n]*", \ +[\w.+-]+@[\w.-]+, \ +\(/[^)\s]*\) + ([\w-]+\.)+(?:json|jsonl|png|jpe?g|gif|svg|mdx?|txt|ya?ml|xml|com|dev|io|ts|js|tsx|jsx), \ [\w-]+="[^"\n]*", \ [\w.+-]+@[\w.-]+, \ \(/[^)\s]*\) BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({(?!/\*).+?})$, \ -(?sm)^[ \t]*```[\s\S]*?```$ +(?sm)^({(?!/\*)(?!/\*).+??})$, \ +(?sm)^[ \t]*[ \t]*```[\s\S]*?```$ CommentDelimiters = {/*, */} @@ -38,6 +43,20 @@ CommentDelimiters = {/*, */} BasedOnStyles = "" # Code-generator snippet with no prose content +# Code-generator snippet with no prose content +[snippets/vercel-json-generator.mdx] +BasedOnStyles = "" + +# Component docs use dotted JSX names (Color.Row, Tree.Folder) that +# false-positive the sentence-spacing rule +[components/{color,tree}.mdx] +Mintlify.Spacing = NO + +# Vale lints /api-playground/... link targets in these files in a pass +# that ignores in-document toggles +[{api-playground/asyncapi-setup.mdx,organize/settings-reference.mdx}] +Vale.Terms = NO + [snippets/vercel-json-generator.mdx] BasedOnStyles = "" diff --git a/ai-native.mdx b/ai-native.mdx index 73b1e4ceb..c6a2d1655 100644 --- a/ai-native.mdx +++ b/ai-native.mdx @@ -2,9 +2,14 @@ title: "AI-native documentation" sidebarTitle: "AI-native" description: "Discover how AI-native features enhance reading, writing, and discovering your documentation with the assistant, agent, and MCP server." -keywords: ["AI","assistant","agent","llms.txt","MCP","llms-full.txt"] +keywords: ["AI", "assistant", "agent", "llms.txt", "MCP", "llms-full.txt"] --- +| rob | | | +| --- | --- | --- | +| | | | +| | | | + When you host your documentation on Mintlify, built-in AI features help your users find answers and your team maintain content more efficiently. Your content provides the context for these AI-native features to improve the experiences of reading, writing, and discovering your documentation. ## What makes your documentation AI-native @@ -49,10 +54,12 @@ Select any of the following cards for more information. Configure the assistant to search external sites or direct people to your support team if it can't answer their questions. + Get documentation updates automatically on a schedule or when a push event occurs. + Add a menu to pages that lets users query AI tools, connect to your MCP server, and copy pages as context with one click. - + \ No newline at end of file diff --git a/ai/llmstxt.mdx b/ai/llmstxt.mdx index d4902743f..bf40b1617 100644 --- a/ai/llmstxt.mdx +++ b/ai/llmstxt.mdx @@ -9,7 +9,7 @@ import { PreviewButton } from "/snippets/previewbutton.jsx" The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines. AI tools can use this file to understand your documentation structure and find content relevant to user queries. -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. +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. Authentication affects `llms.txt` and `llms-full.txt` differently depending on your site configuration: @@ -80,4 +80,4 @@ Mintlify automatically hosts an `llms-full.txt` file at the root of your project To add a custom `llms.txt` or `llms-full.txt` file, create an `llms.txt` or `llms-full.txt` file at the root of your project. Adding a custom file overrides the automatically generated file of the same name. If you delete a custom file, Mintlify restores the automatically generated file. -Your custom `llms.txt` or `llms-full.txt` file must have a site title as an H1 heading. Other content is optional. See [Format](https://llmstxt.org/#format) in the `llms.txt` specification for more information on optional sections and best practices. +Your custom `llms.txt` or `llms-full.txt` file must have a site title as an H1 heading. Other content is optional. See [Format](https://llmstxt.org/#format) in the `llms.txt` specification for more information on optional sections and best practices. \ No newline at end of file diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx index 267467b4b..bafbea8de 100644 --- a/ai/mintlify-mcp.mdx +++ b/ai/mintlify-mcp.mdx @@ -9,7 +9,7 @@ keywords: ["MCP", "write access", "AI", "editing", "Claude", "Cursor", "branch", 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 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. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them. +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. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them. 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. @@ -17,6 +17,8 @@ Connect any MCP client like Claude, Claude Code, or Cursor to the admin MCP serv The admin MCP is a hosted Mintlify service at `https://mcp.mintlify.com`. Every client connects to the same endpoint and authenticates with your Mintlify account. +The admin MCP is a hosted Mintlify service at `https://mcp.mintlify.com`. Every client connects to the same endpoint and authenticates with your Mintlify account. + ### How the admin MCP differs from the search MCP | | Admin MCP | Search MCP | @@ -26,17 +28,21 @@ The admin MCP is a hosted Mintlify service at `https://mcp.mintlify.com`. Every | **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 | -## Prerequisites +## PrerequisitesPrerequisites + +Before connecting the admin MCP, confirm the following:Before connecting the admin MCP, confirm the following: -Before connecting the admin MCP, confirm the following: +- **Mintlify account**: You need a Mintlify account with access to the project you want to edit. The OAuth session inherits your dashboard permissions, so admin-only actions (such as `update_config` on protected settings) require an admin role on the project. +- **Git provider access**: The Mintlify GitHub App or GitLab connection for the project must have write access to the deploy branch's repository. `save` opens PRs through the same integration used for normal deploys. +- **MCP client**: An MCP-capable AI tool such as Claude, Claude Code, Cursor, or Codex. - **Mintlify account**: You need a Mintlify account with access to the project you want to edit. The OAuth session inherits your dashboard permissions, so admin-only actions (such as `update_config` on protected settings) require an admin role on the project. - **Git provider access**: The Mintlify GitHub App or GitLab connection for the project must have write access to the deploy branch's repository. `save` opens PRs through the same integration used for normal deploys. - **MCP client**: An MCP-capable AI tool such as Claude, Claude Code, Cursor, or Codex. -## Connect to the admin MCP +## Connect to the admin MCPConnect to the admin MCP -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 or more deployments, depending on how you grant access. A connection scoped to specific deployments can only check out those, while an organization-wide connection can check out any deployment in your organization. +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.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. 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 or more deployments, depending on how you grant access. A connection scoped to specific deployments can only check out those, while an organization-wide connection can check out any deployment in your organization. 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 or more deployments, depending on how you grant access. A connection scoped to specific deployments can only check out those, while an organization-wide connection can check out any deployment in your organization. @@ -44,7 +50,7 @@ You must have an interactive OAuth login against your Mintlify account to connec 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. 2. Click **Add custom connector**. - 3. Add the connector: + 3. Add the connector:: - Name: Admin MCP - URL: `https://mcp.mintlify.com` 4. Click **Add** and complete the OAuth login. @@ -80,6 +86,29 @@ You must have an interactive OAuth login against your Mintlify account to connec 4. Reload Cursor and complete the OAuth login when prompted. + + + + 1. Open Claude Desktop settings and navigate to **Developer** \> **Edit Config**. + 2. Add the admin MCP server to `claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "mintlify": { + "url": "https://mcp.mintlify.com" + } + } + } + ``` + + 3. Restart Claude Desktop and complete the OAuth login when prompted. + + + Select the Mintlify admin MCP from the tools menu in a new chat. Claude Desktop can now call the admin MCP tools while answering your prompt. + + + Add the admin MCP server to your Codex CLI config at `~/.codex/config.toml`: @@ -99,13 +128,16 @@ You must have an interactive OAuth login against your Mintlify account to connec Every admin MCP session binds to a single Git branch. The flow is: + + If your connection has access to more than one deployment, call `list_deployments` to see which `subdomain` values you can check out. Skip this step if your connection covers only a single deployment. + If your connection has access to more than one deployment, call `list_deployments` to see which `subdomain` values you can check out. Skip this step if your connection covers only a single deployment. - The first required call is `checkout {subdomain}`. It creates a fresh `mintlify-mcp/-` branch from that deployment's deploy branch (or attaches to an existing branch you name) and returns an `editorUrl` you can open to follow along in the dashboard editor. + The first required call is `checkout {subdomain}`. It creates a fresh `mintlify-mcp/-` branch from that deployment'srequired call is `checkout {subdomain}`. It creates a fresh `mintlify-mcp/-` branch from that deployment's deploy branch (or attaches to an existing branch you name) and returns an `editorUrl` you can open to follow along in the dashboard editor. - Call `list_branches` before `checkout` if you need to discover or filter existing branches in a deployment's repository. + Call `list_branches` before `checkout` if you need to discover or filter existing branches in a deployment'sa deployment's repository. The AI uses tools like `search`, `read`, `list_nodes`, `edit_page`, `write_page`, `create_node`, and `update_config` to make changes. All edits buffer on the session branch in real time—nothing touches your deploy branch yet. @@ -122,12 +154,121 @@ Every admin MCP session binds to a single Git branch. The flow is: - If your connection has access to multiple deployments, each checked-out deployment keeps its own session and branch in memory at the same time. - + If your connection has access to multiple deployments, each checked-out deployment keeps its own session and branch in memory at the same timeIf your connection has access to multiple deployments, each checked-out deployment keeps its own session and branch in memory at the same time. + + Calling `checkout` again with a different `subdomain` or branch switches which session is active. It doesn't discard the others. To abandon an in-progress draft instead of switching away from it, call `discard_session`. + Calling `checkout` again with a different `subdomain` or branch switches which session is active. It doesn't discard the others. To abandon an in-progress draft instead of switching away from it, call `discard_session`. -## What the admin MCP can do + + + + + 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. + 2. Click **Add custom connector**. + 3. Add the connector + - Name: Admin MCP + - URL: `https://mcp.mintlify.com` + 4. Click **Add** and complete the OAuth login. + + + 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 admin MCP server with the Claude Code CLI: + + ```bash + claude mcp add --transport http mintlify https://mcp.mintlify.com + ``` + + On first use, Claude Code opens a browser window to complete the OAuth login. After authenticating, the session is reused for subsequent calls. + + + 1. Open the command palette with Command \+ Shift \+ P (Ctrl \+ Shift \+ P on Windows). + 2. Search for **Open MCP settings** and click **Add custom MCP**. + 3. In `mcp.json`, add the admin MCP: + + ```json + { + "mcpServers": { + "mintlify": { + "url": "https://mcp.mintlify.com" + } + } + } + ``` + + 4. Reload Cursor and complete the OAuth login when prompted. + + + + + 1. Open Claude Desktop settings and navigate to **Developer** \> **Edit Config**. + 2. Add the admin MCP server to `claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "mintlify": { + "url": "https://mcp.mintlify.com" + } + } + } + ``` + + 3. Restart Claude Desktop and complete the OAuth login when prompted. + + + Select the Mintlify admin MCP from the tools menu in a new chat. Claude Desktop can now call the admin MCP tools while answering your prompt. + + + + + Add the admin MCP server to your Codex CLI config at `~/.codex/config.toml`: + + ```toml + [mcp_servers.mintlify] + url = "https://mcp.mintlify.com" + ``` + + On first use, Codex opens a browser window to complete the OAuth login. After authenticating, the session is reused for subsequent calls. + + See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details. + + + +## How a session works + +Every admin MCP session binds to a single Git branch. The flow is: + + + + The first call must be `checkout`. It creates a fresh `mintlify-mcp/-` branch from your deploy branch (or attaches to an existing branch you name) and returns an `editorUrl` you can open to follow along in the dashboard editor. + + Call `list_branches` before `checkout` if you need to discover or filter existing branches in the repository. + + + The AI uses tools like `search`, `read`, `list_nodes`, `edit_page`, `write_page`, `create_node`, and `update_config` to make changes. All edits buffer on the session branch in real time—nothing touches your deploy branch yet. + + + Call `diff` at any time to see exactly what changed since `main`. Open the `editorUrl` in your dashboard to see the same changes rendered. + + + Call `save` to flush the branch to Git. Use `mode: "pr"` (default) to open a pull request, or `mode: "commit"` to push directly to an existing PR branch. + + + Call `discard_session` to drop all in-session changes and release the branch. + + + + + 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 admin MCP can doWhat the admin MCP can do ### Content @@ -150,15 +291,81 @@ Every admin MCP session binds to a single Git branch. The flow is: ### Session -- **`list_deployments`** — List the deployments your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass to `checkout`. -- **`checkout`** — Bind a session to a branch for a given deployment `subdomain`, or switch which deployment's session is active. -- **`list_branches`** — List Git branches available for a deployment's project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name. -- **`get_session_state`** — Inspect the current branch, edited files, and pending nav diff. +### Content + +- **`read`** — Fetch the full MDX of any page on the session branch. +- **`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 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 paginate 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. +- **`delete_node`** — Remove a node from the navigation. + +### Configuration + +- **`update_config`** — Modify `docs.json` (theme, navigation roots, integrations, SEO settings). + +### Session + +- **`list_deployments`** — List the deployments your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass to `checkout**list_deployments**` — List the deployments your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass to `checkout`. +- **`checkout`** — Bind the session to a branch.**`checkout`** — Bind the session to a branch. **`checkout`** — Bind a session to a branch for a given deployment `subdomain`, or switch which deployment's session is activ**`checkout`** — Bind the session to a branch.**`checkout`** — Bind the session to a branch. **`checkout`** — Bind a session to a branch for a given deployment `subdomain`, or switch which deployment's session is active. +- **`list_branches`** — List Git branches available for the project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name.**`list_branches`** — List Git branches available for the project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name. **`list_branches`** — List Git branches available for a deployment's project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name. +- **`list_branches`** — List Git branches available for the project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name.**`list_branches`** — List Git branches available for the project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name. **`list_branches`** — List Git branches available for a deployment's project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name. +- **`get_session_state`** — Inspect the current branch, edited files, and pending nav diff.**`get_session_state`** — Inspect the current branch, edited files, and pending nav diff. +- **`diff`** — List all changes between the session and `main`. +- **`save`** — Open a pull request or commit to the session branch. +- **`discard_session`** — Drop the session and its in-flight changes. - **`diff`** — List all changes between the session and `main`. - **`save`** — Open a pull request or commit to the session branch. - **`discard_session`** — Drop the session and its in-flight changes. -## Example prompts +## Example promptExample prompts + +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'."_ +- _"Reorganize the API reference: move the webhooks pages into a new group called 'Webhooks' and update the icons to match the rest of the section."_ + +## Best practices + + + + Every `checkout` returns an `editorUrl`. Open it in a separate tab so you can watch the AI's changes render live in the dashboard editor while you prompt. + + + + 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. + + + + Pass a `slug` to `checkout` (for example, `add-quickstart`) so the auto-generated branch is human-readable. Without it, the branch name derives from the session token and is hard to recognize in your repository. + + + + Keep each session focused to one change. Smaller sessions produce easier to review pull requests and preserve agents' context windows. Use `discard_session` and `checkout` again to pivot to unrelated work. + + + + + Sessions hold an in-memory branch on the Mintlify side. If you abandon a session without saving or discarding it, the branch persists until your next checkout overwrites it. Avoid leaving stale `mintlify-mcp/*` branches in your repository. Clean them up periodically. + + +## Disconnect or revoke access + +Disconnect the admin MCP when you no longer want an AI tool to edit your project, or when you want to force a fresh OAuth login. + +- **Revoke the OAuth grant**: In your Mintlify dashboard, navigate to **Settings → Security & access → Connected apps** and revoke the entry for the AI tool you connected. Revoking invalidates any active session tokens immediately, so in-flight tool calls fail and the tool must complete a new OAuth login on the next call. +- **Remove the connector in the client**: + - Claude: **Settings → Connectors**, then remove the admin MCP entry. + - Claude Code: `claude mcp remove mintlify`. + - Cursor: delete the `mintlify` entry from `mcp.json` and reload. + - Codex: delete the `[mcp_servers.mintlify]` block from `~/.codex/config.toml`. After you connect the admin MCP, you can drive it with natural-language prompts. For example: @@ -201,4 +408,4 @@ Disconnect the admin MCP when you no longer want an AI tool to edit your project - Cursor: delete the `mintlify` entry from `mcp.json` and reload. - Codex: delete the `[mcp_servers.mintlify]` block from `~/.codex/config.toml`. -Revoking the OAuth grant does not affect pull requests the MCP has already opened. Close or revert those PRs in your Git provider if you want to undo pending changes. \ No newline at end of file +Revoking the OAuth grant does not affect pull requests the MCP has already opened. If you want to undo pending changes, close or revert those PRs in your Git provider.Revoking the OAuth grant does not affect pull requests the MCP has already opened. If you want to undo pending changes, close or revert those PRs in your Git provider.Revoking the OAuth grant does not affect pull requests the MCP has already opened. If you want to undo pending changes, close or revert those PRs in your Git provider. Revoking the OAuth grant does not affect pull requests the MCP has already opened. Close or revert those PRs in your Git provider if you want to undo pending changes. Revoking the OAuth grant does not affect pull requests the MCP has already opened. Close or revert those PRs in your Git provider if you want to undo pending changes. \ No newline at end of file diff --git a/cli/commands.mdx b/cli/commands.mdx index 1c7c515ef..c30ddb382 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -197,7 +197,7 @@ Check for broken internal links in your documentation. mint broken-links [flags] ``` -The command scans `.mdx` and `.md` files for links and excludes files matching [.mintignore](/organize/mintignore) patterns. Links inside OpenAPI specification files (`.yaml`, `.yml`, `.json`) are not checked. Links that point to ignored files report as broken. +The command scans `.mdx` and `.md` files for links and excludes files matching [.mintignore](/organize/mintignore) patterns. Links inside OpenAPI specification files (`.yaml`, `.yml`, `.json`) are not checkedscans `.mdx` and `.md` files for links and excludes files matching [.mintignore](/organize/mintignore) patterns. Links inside OpenAPI specification files (`.yaml`, `.yml`, `.json`) are not checked. Links that point to ignored files report as broken. | Flag | Description | | --- | --- | @@ -395,4 +395,4 @@ You can also disable telemetry by setting one of these environment variables: | `MINTLIFY_TELEMETRY_DISABLED` | `1` | Disable Mintlify CLI telemetry. | | `DO_NOT_TRACK` | `1` | Disable telemetry using the [Console Do Not Track](https://consoledonottrack.com/) standard. | -Your preference saves in `~/.config/mintlify/config.json` and persists across CLI sessions. +Your preference saves in `~/.config/mintlify/config.json` and persists across CLI sessions. \ No newline at end of file diff --git a/cli/install.mdx b/cli/install.mdx index 85df56afa..0ee2b8afc 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -6,18 +6,20 @@ keywords: ["CLI", "npm", "install", "Node.js", "pnpm", "mint"] ## Prerequisites -- [Node.js](https://nodejs.org/en) v20.17.0+ (LTS versions recommended) +- [Node.js](https://nodejs.org/en) v20.17.0\+ (LTS versions recommended) qowij foawij efoaijw eofiaw efawe fawe f ## Install the CLI - ```bash npm - npm i -g mint - ``` - ```bash pnpm - pnpm add -g mint - ``` +```bash npm +npm i -g mint +``` + +```bash pnpm +pnpm add -g mint +``` + ## Create a new project @@ -68,13 +70,15 @@ mint update If `mint update` is not available on your version, reinstall the CLI with the latest version: - ```bash npm - npm i -g mint@latest - ``` - ```bash pnpm - pnpm add -g mint@latest - ``` +```bash npm +npm i -g mint@latest +``` + +```bash pnpm +pnpm add -g mint@latest +``` + ## Formatting @@ -91,22 +95,26 @@ For syntax highlighting and code formatting in MDX files, use the following exte This may be due to an outdated version of Node.js. Try the following: 1. Remove the currently installed version of the mint CLI: `npm uninstall -g mint` - 2. Upgrade to Node.js v20.17.0+. + 2. Upgrade to Node.js v20.17.0\+. 3. Reinstall the mint CLI: `npm install -g mint` + **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again. + This is due to not having the required permissions to globally install node packages. **Solution**: Try running `sudo npm i -g mint`. When prompted, enter the password that you use to unlock your computer. + This is likely due to an outdated version of the CLI. **Solution**: Run `mint update` to get the latest changes. + If you have any problems with the CLI package, first run `npm ls -g` to see what packages are globally installed. If you don't use npm, try `which mint` to locate the installation. @@ -118,16 +126,15 @@ For syntax highlighting and code formatting in MDX files, use the following exte npm i -g mint ``` + If you run `mint version` and the client version displays as `none`, the CLI may be unable to download the client application due to a corporate firewall or VPN. **Solution**: Ask your IT administrator to add `releases.mintlify.com` to your network allowlist. + - In versions before `4.0.1125`, running `npx mint dev` or other commands from a docs - repository could cause the CLI to incorrectly detect itself as a local development - build. This made the CLI point to `localhost` URLs instead of the Mintlify production - API, resulting in connection errors or unexpected behavior. + In versions before `4.0.1125`, running `npx mint dev` or other commands from a docs repository could cause the CLI to incorrectly detect itself as a local development build. This made the CLI point to `localhost` URLs instead of the Mintlify production API, resulting in connection errors or unexpected behavior. **Solution**: Update to the latest CLI version: @@ -135,4 +142,4 @@ For syntax highlighting and code formatting in MDX files, use the following exte npm i -g mint@latest ``` - + \ No newline at end of file diff --git a/credits.mdx b/credits.mdx index 4c6b9c9c6..61f511371 100644 --- a/credits.mdx +++ b/credits.mdx @@ -6,9 +6,9 @@ keywords: ["credits", "billing", "pricing", "AI chat", "messages", "tiers", "usa Some Mintlify features consume credits. -* Assistant responses -* Agent runs in the editor or on Slack -* Automation runs +- Assistant responses +- Agent runs in the editor or on Slack +- Automation 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. @@ -16,6 +16,25 @@ For the most current pricing information, see the [Pricing page](https://mintlif Credits are available on the **Pro plan and above**. Every Pro plan includes 10,000 credits per month, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more. +The free Starter plan does not include AI features and has no credit purchase path. To use the assistant, editor and Slack agents, or automations, upgrade to Pro. + + + Customers on legacy credit plans keep their existing credit packs and pricing. The tiers below apply to the Pro plan. + + +## Pricing tiers + +| Monthly credits | Monthly cost | +| :-- | :-- | +| 10,000 | \$0 | +| 25,000 | \$145 | +| 50,000 | \$370 | +| 100,000 | \$800 | + +## Plan availability + +Credits are available on the **Pro plan and above**. Every Pro plan includes 10,000 credits per month, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more. + The free Starter plan does not include AI features. You cannot purchase credits on the starter plan. To use the assistant, agent, or automations, upgrade to Pro or Enterprise. @@ -25,15 +44,15 @@ The free Starter plan does not include AI features. You cannot purchase credits ## Pricing tiers | Monthly credits | Monthly cost | -|:----------------|:-------------| -| 10,000 | $0 | -| 25,000 | $145 | -| 50,000 | $370 | -| 100,000 | $800 | +| :-- | :-- | +| 10,000 | \$0 | +| 25,000 | \$145 | +| 50,000 | \$370 | +| 100,000 | \$800 | If you need more than 100,000 credits per month, [contact sales](https://www.mintlify.com/contact/sales) to discuss a custom plan. -**Overages** cost an additional $0.01 per credit 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** cost an additional \$0.01 per credit 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 default to off. You must enable them on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. @@ -52,7 +71,7 @@ For high-volume usage or custom credit packages, [contact sales](mailto:sales@mi 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 | @@ -60,7 +79,7 @@ Different features consume different amounts of credits per interaction: Automations also consume credits when they run: | Automation | Average credits per run | -|:---------|:------------------------| +| :-- | :-- | | Update from code changes | 180 | | Update from assistant conversations | 212 | | Broken link detection | 285 | @@ -93,4 +112,4 @@ The exported CSV includes the date, product, and credits consumed for each event **Schedule automations instead of triggering on every push.** Automations 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 automation is consuming more credits than expected, review its trigger or any custom instructions. +**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 automation is consuming more credits than expected, review its trigger or any custom instructions. \ No newline at end of file diff --git a/customize/custom-scripts.mdx b/customize/custom-scripts.mdx index 2bede3b03..1054fce68 100644 --- a/customize/custom-scripts.mdx +++ b/customize/custom-scripts.mdx @@ -6,6 +6,8 @@ keywords: ["CSS", "JavaScript", "Tailwind CSS", "style customization"] Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation. +/ + ## Style with Tailwind CSS Use Tailwind CSS v3 to style HTML elements. You can control layout, spacing, colors, and other visual properties. Some common classes are: @@ -59,83 +61,96 @@ Mintlify exposes two types of CSS targeting hooks: Each ID appears once per page. Use these as `#value` in CSS. For example, `#navbar { background: red; }`. - - - `#body-content` — Outermost wrapper for the page body. - - `#content-area` — Primary content area, excluding the sidebar and table of contents. - - `#content` — Inner content element within the content area. - - `#header` — Page-level header element. - - `#banner` — Announcement banner displayed above the navbar. - - `#footer` — Page footer. Also targetable as an element selector: `footer`. - - `#page-title` — The `

` heading at the top of each page. - - `#pagination` — Bottom pagination bar with previous and next page links. - - `#panel` — Floating panel overlay. Also targetable as an element selector: `panel`. - - `#background-color` — Page background color element. - - - - `#navbar` — Top navigation bar. - - `#topbar-cta-button` — Call-to-action button in the topbar. - - `#mobile-nav` — Mobile navigation overlay. - - `#mobile-nav-content` — Content area within the mobile navigation overlay. - - - - `#sidebar` — The sidebar navigation panel. - - `#sidebar-content` — Scrollable content area within the sidebar. - - - - `#table-of-contents` — Table of contents panel on the right side of the page. - - `#table-of-contents-layout` — Layout wrapper for the table of contents. - - `#table-of-contents-content` — Scrollable content within the table of contents. - - - - `#search-bar-entry` — Search bar trigger in the topbar. - - `#search-bar-entry-mobile` — Search bar trigger on mobile. - - `#search-input` — Text input field within the search modal. - - - - `#assistant-entry` — AI assistant button in the topbar. - - `#assistant-entry-mobile` — AI assistant button on mobile. - - `#chat-assistant-sheet` — AI assistant chat panel. - - `#chat-assistant-textarea` — Text input within the AI assistant panel. - - - - `#request-example` — Request example panel in the API playground. - - `#response-example` — Response example panel in the API playground. - - `#api-playground-input` — Input section of the API playground. - - `#endpoints-menu-trigger` — Button that opens the endpoint selector dropdown. - - - - `#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. - - - - `#feedback-thumbs-up` — Thumbs-up feedback button at the bottom of a page. - - `#feedback-thumbs-down` — Thumbs-down feedback button at the bottom of a page. - - `#feedback-form` — Feedback form shown after a thumbs-down response. - - `#feedback-form-input` — Text input within the feedback form. - - `#feedback-form-cancel` — Cancel button within the feedback form. - - `#feedback-form-submit` — Submit button within the feedback form. - - - - `#page-context-menu` — Contextual options menu for the current page. - - `#page-context-menu-button` — Button that triggers the page context menu. - - - - `#localization-select-trigger` — Button that opens the language selector. - - `#localization-select-content` — Dropdown content of the language selector. - - `#localization-select-item` — Individual language option within the selector. - - - - `#changelog-filters` — Filter controls on a changelog page. - - `#changelog-filters-content` — Content area within the changelog filter panel. - - - - `#multi-view-dropdown` — Dropdown for switching between documentation views. - - - - `#text-selection-tooltip` — Tooltip that appears when you select text on a page. - - `#text-selection-tooltip-button` — Action button within the text selection tooltip. - + + - `#body-content` — Outermost wrapper for the page body. + - `#content-area` — Primary content area, excluding the sidebar and table of contents. + - `#content` — Inner content element within the content area. + - `#header` — Page-level header element. + - `#banner` — Announcement banner displayed above the navbar. + - `#footer` — Page footer. Also targetable as an element selector: `footer`. + - `#page-title` — The `

` heading at the top of each page. + - `#pagination` — Bottom pagination bar with previous and next page links. + - `#panel` — Floating panel overlay. Also targetable as an element selector: `panel`. + - `#background-color` — Page background color element. + + + + - `#navbar` — Top navigation bar. + - `#topbar-cta-button` — Call-to-action button in the topbar. + - `#mobile-nav` — Mobile navigation overlay. + - `#mobile-nav-content` — Content area within the mobile navigation overlay. + + + + - `#sidebar` — The sidebar navigation panel. + - `#sidebar-content` — Scrollable content area within the sidebar. + + + + - `#table-of-contents` — Table of contents panel on the right side of the page. + - `#table-of-contents-layout` — Layout wrapper for the table of contents. + - `#table-of-contents-content` — Scrollable content within the table of contents. + + + + - `#search-bar-entry` — Search bar trigger in the topbar. + - `#search-bar-entry-mobile` — Search bar trigger on mobile. + - `#search-input` — Text input field within the search modal. + + + + - `#assistant-entry` — AI assistant button in the topbar. + - `#assistant-entry-mobile` — AI assistant button on mobile. + - `#chat-assistant-sheet` — AI assistant chat panel. + - `#chat-assistant-textarea` — Text input within the AI assistant panel. + + + + - `#request-example` — Request example panel in the API playground. + - `#response-example` — Response example panel in the API playground. + - `#api-playground-input` — Input section of the API playground. + - `#endpoints-menu-trigger` — Button that opens the endpoint selector dropdown. + + + + - `#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. + + + + - `#feedback-thumbs-up` — Thumbs-up feedback button at the bottom of a page. + - `#feedback-thumbs-down` — Thumbs-down feedback button at the bottom of a page. + - `#feedback-form` — Feedback form shown after a thumbs-down response. + - `#feedback-form-input` — Text input within the feedback form. + - `#feedback-form-cancel` — Cancel button within the feedback form. + - `#feedback-form-submit` — Submit button within the feedback form. + + + + - `#page-context-menu` — Contextual options menu for the current page. + - `#page-context-menu-button` — Button that triggers the page context menu. + + + + - `#localization-select-trigger` — Button that opens the language selector. + - `#localization-select-content` — Dropdown content of the language selector. + - `#localization-select-item` — Individual language option within the selector. + + + + - `#changelog-filters` — Filter controls on a changelog page. + - `#changelog-filters-content` — Content area within the changelog filter panel. + + + + - `#multi-view-dropdown` — Dropdown for switching between documentation views. + + + + - `#text-selection-tooltip` — Tooltip that appears when you select textyou select text on a page. + - `#text-selection-tooltip-button` — Action button within the text selection tooltip. + ### Element selectors @@ -165,6 +180,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `tooltip` — Tooltip element. - `update` — Changelog update entry. + - `mdx-content` — Rendered MDX content area. - `panel` — Floating panel component. Also targetable as an ID selector: `#panel`. @@ -173,6 +189,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `breadcrumb-list` — Breadcrumb navigation list. - `breadcrumb-item` — Individual breadcrumb item. + - `nav-logo` — Logo in the navigation bar. - `navbar-link` — Link element within the navigation bar. @@ -185,6 +202,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `nav-tag-pill` — Tag pill shown in the navigation. - `nav-tag-pill-text` — Text within a navigation tag pill. + - `nav-dropdown-trigger` — Button that opens a navigation dropdown. - `nav-dropdown-content` — Content container for a navigation dropdown. @@ -194,6 +212,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `nav-dropdown-item-description` — Description text within a dropdown item. - `nav-dropdown-item-icon` — Icon within a dropdown item. + - `nav-dropdown-products-selector-trigger` — Button that opens the products selector dropdown. - `nav-dropdown-products-selector-content` — Content container for the products selector. @@ -202,6 +221,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `nav-dropdown-products-selector-item-description` — Description of a product selector item. - `nav-dropdown-products-selector-item-icon` — Icon of a product selector item. + - `sidebar-group` — Group of related sidebar links. - `sidebar-group-icon` — Icon for a sidebar group. @@ -209,19 +229,23 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `sidebar-title` — Top-level title in the sidebar. - `sidebar-nav-group-divider` — Divider between sidebar navigation groups. + - `toc` — Table of contents container. - `toc-item` — Individual heading entry in the table of contents. + - `footer` — Standard page footer. Also targetable as an ID selector: `#footer`. - `advanced-footer` — Extended footer with additional columns or content. + - `pagination-prev` — Previous page link in the pagination bar. - `pagination-next` — Next page link in the pagination bar. - `pagination-title` — Page title shown in the pagination bar. + - `api-section` — Full section for a single API endpoint. - `api-section-heading` — Heading area for an API endpoint section. @@ -234,6 +258,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `method-nav-pill` — HTTP method badge shown in the sidebar navigation. - `prompt` — Prompt component in the API reference. + - `chat-assistant-sheet` — AI assistant panel container. - `chat-assistant-sheet-header` — Header of the AI assistant panel. @@ -245,6 +270,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `chat-assistant-payload-item` — Individual message or result item in the assistant panel. - `starter-question-text` — Suggested starter question shown in an empty assistant panel. + - `feedback-toolbar` — Toolbar containing page feedback controls. - `contextual-feedback-container` — Container for contextual inline feedback. @@ -254,6 +280,7 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `contextual-feedback-button` — Action button within the contextual feedback form. - `contextual-feedback-form-submit-button` — Submit button for the contextual feedback form. + - `code-snippet-feedback-popover-content` — Popover content for code snippet feedback. - `code-snippet-feedback-form` — Feedback form for a code snippet. @@ -262,10 +289,12 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `code-snippet-feedback-form-description` — Description text in the code snippet feedback form. - `code-snippet-feedback-form-submit-button` — Submit button for the code snippet feedback form. + - `login-link` — Link that initiates the login flow. - `logout-link` — Link that initiates the logout flow. + - `multi-view-item` — Individual view option in a multi-view switcher. - `multi-view-dropdown` — Dropdown for selecting between multiple views. @@ -273,12 +302,14 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `multi-view-dropdown-content` — Content area of the multi-view dropdown. - `multi-view-dropdown-item` — Individual item within the multi-view dropdown. + - `directory` — Root container for a directory page. - `directory-group` — Group of related pages within a directory. - `directory-page` — Individual page entry in a directory. - `directory-card` — Card-style page entry in a directory. + - `not-found-container` — Root container of the 404 page. - `not-found-status-code` — Status code display on the 404 page. @@ -287,16 +318,19 @@ Multiple instances of these elements can appear on a page. Use these as `value` - `not-found-recommended-pages-list` — List of recommended pages shown on the 404 page. - `not-found-recommended-page-link` — Individual link in the recommended pages list. + - `color` — Color swatch element. - `color-row` — Row grouping color swatches. - `color-item` — Individual color item within a color row. + - `tree` — File tree container. - `tree-folder` — Folder entry within a file tree. - `tree-file` — File entry within a file tree. + Some elements expose data attributes you can use as CSS selectors. diff --git a/customize/fonts.mdx b/customize/fonts.mdx index d6bc0e1e7..845dc9584 100644 --- a/customize/fonts.mdx +++ b/customize/fonts.mdx @@ -26,33 +26,32 @@ To use local fonts, place your font files in your project directory and referenc ### Set up local fonts - -For example, create a `fonts` directory and add your font files: - -```text -your-project/ -├── fonts/ -│ ├── InterDisplay-Regular.woff2 -│ └── InterDisplay-Bold.woff2 -├── docs.json -└── ... -``` - - - -Reference your local fonts using relative paths from your project root: - -```json docs.json -{ - "fonts": { - "family": "InterDisplay", - "source": "/fonts/InterDisplay-Regular.woff2", - "format": "woff2", - "weight": 400 - } -} -``` - + + For example, create a `fonts` directory and add your font files: + + ```text + your-project/ + ├── fonts/ + │ ├── InterDisplay-Regular.woff2 + │ └── InterDisplay-Bold.woff2 + ├── docs.json + └── ... + ``` + + + Reference your local fonts using relative paths from your project root: + + ```json docs.json + { + "fonts": { + "family": "InterDisplay", + "source": "/fonts/InterDisplay-Regular.woff2", + "format": "woff2", + "weight": 400 + } + } + ``` + ### Local fonts for headings and body @@ -102,15 +101,19 @@ Use externally hosted fonts by referencing a font source URL in your `docs.json` Font family name, such as "Inter" or "Playfair Display." + Font weight, such as 400 or 700. Variable fonts support precise weights such as 550. + - URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file, such as `/assets/fonts/InterDisplay.woff2`. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URL. + URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file, such as `/assets/fonts/InterDisplay.woff2`. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URLload automatically when you specify a Google Font `family` name, so you don't need a source URL. + Font file format. Required when using the `source` field. + Override font settings specifically for headings. @@ -118,17 +121,21 @@ Use externally hosted fonts by referencing a font source URL in your `docs.json` Font family name for headings. + Font weight for headings. + - URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for headings. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URL. + URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for headings. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URLload automatically when you specify a Google Font `family` name, so you don't need a source URL. + Font file format for headings. Required when using the `source` field. + Override font settings specifically for body text. @@ -136,16 +143,19 @@ Use externally hosted fonts by referencing a font source URL in your `docs.json` Font family name for body text. + Font weight for body text. + - URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for body text. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URL. + URL to your font source, such as `https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2`, or path to your local font file for body text. Google Fonts load automatically when you specify a Google Font `family` name, so you don't need a source URLload automatically when you specify a Google Font `family` name, so you don't need a source URL. + Font file format for body text. Required when using the `source` field. - + \ No newline at end of file diff --git a/optimize/analytics.mdx b/optimize/analytics.mdx index 3a224d86a..23f1fcbaa 100644 --- a/optimize/analytics.mdx +++ b/optimize/analytics.mdx @@ -1,7 +1,7 @@ --- title: "Analytics" description: "Track documentation analytics in the Mintlify dashboard to understand page views, visitor trends, search queries, and content effectiveness." -keywords: ["analytics","metrics","page views","traffic","trends","insights"] +keywords: ["analytics", "metrics", "page views", "traffic", "trends", "insights"] boost: 3 --- @@ -17,15 +17,14 @@ Filter your analytics data by traffic source to analyze AI agent traffic separat The traffic source filter on the analytics page. - The traffic source filter on the analytics page. @@ -37,15 +36,14 @@ Use the range selector to adjust the time period for displayed data. The range selector expanded to show options for viewing different time periods of data. - The range selector expanded to show options for viewing different time periods of data. @@ -59,9 +57,11 @@ Review your visitors analytics to: - **Identify popular pages**: Use popular pages to understand what content is most important to your users so that you can make sure it is up to date and comprehensive. - **Track traffic sources**: Understand where your users are coming from to help you optimize your content for the right audience. -### Agent visitors +### Agent visitorAgent visitors + +Agent visitors are identified by IP address and user agent. The agent visitor count approximates distinct sources of AI traffic rather than individual agent sessions or conversations. Multiple requests from the same IP address count as one visitor.Agent visitors are identified by IP address and user agent. The agent visitor count approximates distinct sources of AI traffic rather than individual agent sessions or conversations. Multiple requests from the same IP address count as one visitor. Mintlify identifies agent visitors by IP address and user agent. The agent visitor count approximates distinct sources of AI traffic rather than individual agent sessions or conversations. Multiple requests from the same IP address count as one visitor. Mintlify identifies agent visitors by IP address and user agent. The agent visitor count approximates distinct sources of AI traffic rather than individual agent sessions or conversations. Multiple requests from the same IP address count as one visitor. -Mintlify identifies agent visitors by IP address and user agent. The agent visitor count approximates distinct sources of AI traffic rather than individual agent sessions or conversations. Multiple requests from the same IP address count as one visitor. +When viewing agent traffic, top agents replaces referrals in the visitors tab. Top agents shows which AI agents are visiting your documentation. Use this information to help determine: When viewing agent traffic, top agents replaces referrals in the visitors tab. Top agents shows which AI agents are visiting your documentation. Use this information to help determine: @@ -94,15 +94,14 @@ The categories tab uses LLMs to automatically group conversations by topic or th The categories tab in the assistant analytics page. - The categories tab in the assistant analytics page. @@ -121,7 +120,7 @@ Click any message to view the complete chat thread, including the user's questio ## Searches -The Searches metric is only available when viewing human traffic. + The Searches metric is only available when viewing human traffic. The searches tab displays a bar chart of searches over time and specific queries. @@ -135,10 +134,10 @@ Review your searches analytics to: ## MCP searches -The MCP Searches metric is only available when viewing AI traffic. + The MCP Searches metric is only available when viewing AI traffic. -The MCP searches tab displays AI agent search interactions through the Model Context Protocol (MCP). This metric counts calls to your MCP server's search tool. It reflects agents that users connected to your MCP server and then issued a search, not general AI crawler traffic to your docs pages. +The MCP searches tab displays AI agent search interactions through the Model Context Protocol (MCP). This metric counts calls to your MCP server's search tool, so it reflects agents that users connected to your MCP server and issued a search, not general AI crawler traffic to your docs pagescounts calls to your MCP server's search tool, so it reflects agents that users connected to your MCP server and issued a search, not general AI crawler traffic to your docs pages. The MCP searches tab displays AI agent search interactions through the Model Context Protocol (MCP). This metric counts calls to your MCP server's search tool. It reflects agents that users connected to your MCP server and then issued a search, not general AI crawler traffic to your docs pages. The MCP searches tab displays AI agent search interactions through the Model Context Protocol (MCP). This metric counts calls to your MCP server's search tool. It reflects agents that users connected to your MCP server and then issued a search, not general AI crawler traffic to your docs pages. Review your MCP searches analytics to: @@ -157,10 +156,10 @@ See [Feedback](/optimize/feedback) for more information on using feedback data t Export any analytics tab to CSV for deeper analysis, reporting, or archival. Exports respect the current traffic source and time range filters. 1. Navigate to the [analytics](https://app.mintlify.com/products/analytics/) page of your dashboard. -1. Click the tab you want to export. -1. Optionally, adjust the traffic source and time range to narrow down the data you want to export. -1. Click **Export to CSV**. -1. Mintlify sends you an email with a download link when the export is ready. +2. ClickClick the tab you want to export. +3. Optionally, adjust the traffic source and time range to narrow down the data you want to export. +4. Click **Export to CSV**. +5. Mintlify sends you an email with a download link when the export is ready. ### Assistant exports @@ -172,4 +171,4 @@ Assistant exports include the queries, responses, sources, and a `resolutionStat - List any queries that had no sources cited. - Find patterns in unsuccessful interactions. - Group unanswered queries by topic to prioritize content updates. - + \ No newline at end of file diff --git a/optimize/search.mdx b/optimize/search.mdx index 3e75dac89..c8b127f62 100644 --- a/optimize/search.mdx +++ b/optimize/search.mdx @@ -99,7 +99,7 @@ To exclude a page from both in-product search and external indexing, use [`noind Control how many results the search bar returns per query from your dashboard. The default is `6` results. You can set any value between `1` and `100`. -In your dashboard, navigate to **Settings** > **Deployment** > **Search**, set **Maximum search results** to the value you want, and select **Save changes**. +In your dashboard, navigate to **Settings** \> **Deployment** \> **Search**, set **Maximum search results** to the value you want, and select **Save changes**. **Deployment** > **Search**, set * /> -Higher values surface more matches per query, which is useful for sites with broad topic coverage where users expect to scan many candidates. Lower values keep the results panel compact and push users toward the top-ranked match. +Higher values surface more matches per query, which is useful for sites with broad topic coverage where users expect to scan many candidates. Lower values keep the results panel compact and push users toward the top-ranked match. \ No newline at end of file diff --git a/organize/hidden-pages.mdx b/organize/hidden-pages.mdx index cc8dccfd5..04bad7b22 100644 --- a/organize/hidden-pages.mdx +++ b/organize/hidden-pages.mdx @@ -14,6 +14,12 @@ Use hidden pages for content you want users to access or reference as context fo If your content requires strict access control, you must configure [authentication](/deploy/authentication-setup). To restrict pages to specific user groups, set up [group-based access control](/deploy/authentication-setup#control-access-with-groups). + + Hidden pages are not private. Anyone with the URL can view them, and links shared externally still work. Hiding a page only removes it from the rendered navigation. + + If your content requires strict access control, you must configure [authentication](/deploy/authentication-setup). To restrict pages to specific user groups, set up [group-based access control](/deploy/authentication-setup#control-access-with-groups). + + See an [example of a hidden page](/organize/hidden-page-example). @@ -99,7 +105,7 @@ By default, hidden pages don't appear in indexing for search engines, documentat The following table summarizes how each property affects page visibility and indexing: | Property | Sidebar navigation | Site search | Sitemap | Search engine indexing | AI assistant context | -|---|---|---|---|---|---| +| --- | --- | --- | --- | --- | --- | | `hidden: true` | Hidden | Excluded | Excluded | Excluded | Excluded | | `noindex: true` | Visible | Excluded | Excluded | Excluded | Excluded | | `searchable: false` (page frontmatter) | Visible | Excluded | Included | Included | Excluded | @@ -159,6 +165,6 @@ Page-level `searchable` does not override `hidden: true` on the same page. To ma The relationship between `hidden` and `noindex` is one-directional: - **`hidden: true` → automatically applies `noindex`**: Hidden pages are automatically excluded from search engines, sitemaps, and AI context. -- **`noindex: true` → does NOT apply `hidden`**: Pages with `noindex: true` remain visible in navigation. They don't appear in site search, sitemaps, search engine indexing, or AI assistant context. +- **`noindex: true` → does NOT apply `hidden`**: Pages with `noindex: true` remain visible in navigation. They don't appear in site search, sitemaps, search engine indexing, ordon't appear in site search, sitemaps, search engine indexing, or AI assistant context. To exclude a specific page from search and indexing while keeping it visible in navigation, add `noindex: true` to its frontmatter. To hide a page from navigation as well, use `hidden: true`. To exclude a page only from your in-product search and AI assistant context while keeping it indexable by external search engines, use [`searchable: false`](/optimize/search#exclude-a-page-from-search) instead. \ No newline at end of file diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 44f8bddeb..59a892700 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -11,9 +11,23 @@ With proper navigation configuration, you can organize your content so that user Choose one primary organizational pattern at the root level of your navigation. Once you've chosen your primary pattern, you can nest other navigation elements within it. -### Choose a primary pattern +### Choose a primary patternChoose a primary pattern -Use the pattern that matches how you want visitors to move between top-level sections of your content. +Use the pattern that matches how you want visitors to move between top-level sections of your contentUse the pattern that matches how you want visitors to move between top-level sections of your content. + +| Pattern | Use when | Example | +| --- | --- | --- | +| [Groups](#groups) | Your content fits in one linear sidebar and you don't need a second axis of navigation. | A single-product SDK reference. | +| [Tabs](#tabs) | You have parallel sections that share the same audience. | Guides, API reference, and SDKs tabs for one product. | +| [Anchors](#anchors) | You want persistent links to a small number of top-level destinations (external or internal) visible at all times. | Community, status page, or another link alongside your product documentation. | +| [Dropdowns](#dropdowns) | Similar to tabs, but you want to use a dropdown menu for navigation. | Switching between product documentation, API reference, and partner integrations. | +| [Products](#products) | You maintain documentation for multiple distinct products under one deployment, and each product has its own full site. | A platform with separate content for Payments, Identity, and Analytics. | +| [Versions](#versions) | You publish multiple versions of the same content in parallel. | Maintaining `v1` and `v2` API docs simultaneously. | +| [Languages](#languages) | You publish translated versions of the same content. | English, Spanish, and Japanese documentation for one product. | + +## Pages + +Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. | Pattern | Use when | Example | | --- | --- | --- | @@ -30,15 +44,14 @@ Use the pattern that matches how you want visitors to move between top-level sec Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. Decorative graphic of pages. - Decorative graphic of pages. In the `navigation` object, `pages` is an array where each entry must reference the path to a [page file](/organize/pages). @@ -62,15 +75,14 @@ In the `navigation` object, `pages` is an array where each entry must reference Use groups to organize your sidebar navigation into sections. You can nest groups within each other, label them with tags, and style them with icons. Decorative graphic of groups. - Decorative graphic of groups. In the `navigation` object, `groups` is an array where each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, and `expanded` fields are optional. @@ -138,7 +150,7 @@ Use the `directory` property to automatically render a directory of child pages The `directory` property accepts three values: | Value | Behavior | -| :---------- | :------- | +| :-- | :-- | | `"none"` | No directory listing. Default value. | | `"accordion"` | Displays child pages in a collapsible list grouped by section. | | `"card"` | Displays child pages in a horizontal card layout. | @@ -181,6 +193,7 @@ You can set `directory` anywhere in the navigation object in your `docs.json` fi ``` In this example: + - **Help Center** uses `"accordion"` and its root page displays a directory listing. - **Getting Started** inherits `"accordion"` from its parent and also displays a directory listing. - **API Reference** overrides with `"none"`, so its root page does not display a directory listing. @@ -197,7 +210,7 @@ Use the `expanded` property to control the default state of a nested group in th - `expanded: false` or omitted: Collapses the group by default. - The `expanded` property only affects nested groups—groups within groups. Top-level groups always expand and you cannot collapse them. + The `expanded` property only affects nested groups——groups within groups. Top-level groups always expand and you cannot collapse them. ```json @@ -219,15 +232,14 @@ Use the `expanded` property to control the default state of a nested group in th Tabs create distinct sections of your documentation with separate URL paths. Tabs create a horizontal navigation bar at the top of your documentation that lets users switch between sections. Decorative graphic of a tab navigation. - Decorative graphic of a tab navigation. In the `navigation` object, `tabs` is an array where each entry is an object that requires a `tab` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. @@ -317,15 +329,14 @@ Menu items can only contain groups, pages, and external links. Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action. Decorative graphic of an anchor navigation. - Decorative graphic of an anchor navigation. In the `navigation` object, `anchors` is an array where each entry is an object that requires an `anchor` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. @@ -392,15 +403,14 @@ Global anchors support both external URLs and relative paths to pages within you ## Products Decorative graphic of a product switcher. - Decorative graphic of a product switcher. Products create a dedicated navigation division for organizing product-specific documentation. Use products to separate different offerings, services, or major feature sets within your documentation. @@ -458,15 +468,14 @@ In the `navigation` object, `products` is an array where each entry is an object Dropdowns are an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation. Decorative graphic of a dropdown navigation. - Decorative graphic of a dropdown navigation. In the `navigation` object, `dropdowns` is an array where each entry is an object that requires a `dropdown` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. @@ -510,7 +519,7 @@ Set a default OpenAPI specification at any level of your navigation hierarchy. C When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification. - + To control which endpoints appear, explicitly list the desired endpoints in a `pages` array. @@ -548,15 +557,14 @@ For more information about referencing OpenAPI endpoints in your docs, see the [ Partition your navigation into different versions. Versions are selectable from a dropdown menu. Decorative graphic of a version switcher. - Decorative graphic of a version switcher. In the `navigation` object, `versions` is an array where each entry is an object that requires a `version` field and can contain any other navigation fields. @@ -668,20 +676,19 @@ Add a badge label to version entries in the version selector dropdown using the Partition your navigation into different languages. Languages are selectable from a dropdown menu. Decorative graphic of a language switcher. - Decorative graphic of a language switcher. In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields, including language-specific banner, footer, and navbar configurations. -Mintlify supports the following languages for localization: +Mintlify supportsMintlify supports the following languages for localization: | Language | Code | | --- | --- | @@ -1058,6 +1065,7 @@ When a user expands a navigation group, some themes automatically navigate to th - Leave unset to use the theme's default behavior. + ```json Force navigation "interaction": { "drilldown": true // Force navigation to first page when a user expands a dropdown @@ -1069,4 +1077,5 @@ When a user expands a navigation group, some themes automatically navigate to th "drilldown": false // Never navigate, only expand or collapse the group } ``` - + + \ No newline at end of file diff --git a/organize/pages.mdx b/organize/pages.mdx index 2afddd995..dc0ddd6bb 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -35,8 +35,9 @@ Use frontmatter to control: The icon to display. - + Options: + - [Font Awesome icon](https://fontawesome.com/icons) name - [Lucide icon](https://lucide.dev/icons) name - [Tabler icon](https://tabler.io/icons) name @@ -46,7 +47,7 @@ Use frontmatter to control: For [Font Awesome](https://fontawesome.com/icons) icons only. The style of the icon. - + Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. @@ -67,7 +68,7 @@ Use frontmatter to control: - Multiply the page's in-product search ranking by this factor. Use values greater than `1` to prioritize the page and values between `0` and `1` to de-prioritize it. See [Search](/optimize/search#boost-search-ranking) for details. `boost` has no effect when `searchable: false`, since the page doesn't appear in in-product search results. + Multiply the page's in-product search ranking by this factor. Use values greater than `1` to prioritize the page and values between `0` and `1` to de-prioritize it. See [Search](/optimize/search#boost-search-ranking) for details. `boost` has no effect when `searchable: false`, since the page doesn't appear indoesn't appear in in-product search results. @@ -213,7 +214,7 @@ keywords: ['configuration', 'setup', 'getting started'] ## Last modified timestamp -Show a "Last modified on [date]" timestamp on all pages by enabling `metadata.timestamp` in your [global settings](/organize/settings-seo#metadata). +Show a "Last modified on \[date\]" timestamp on all pages by enabling `metadata.timestamp` in your [global settings](/organize/settings-seo#metadata). ```json docs.json "metadata": { @@ -232,4 +233,4 @@ timestamp: false --- ``` -If you set `timestamp: true`, the page always shows the timestamp even if the global setting is `false`. If you set `timestamp: false`, the page hides the timestamp even if the global setting is `true`. +If you set `timestamp: true`, the page always shows the timestamp even if the global setting is `false`. If you set `timestamp: false`, the page hides the timestamp even if the global setting is `true`. \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index 4fc7601ca..e14dce0bb 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -11,7 +11,7 @@ After you complete this guide, you'll have a live documentation site ready to cu ## Before you begin -Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository. +Mintlify. uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository. When you connect your documentation repository to your project, you can work on your documentation locally or in the web editor and sync any changes to your remote repository. @@ -21,8 +21,6 @@ When you connect your documentation repository to your project, you can work on Copy the following prompt to add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your documentation. - - ## Deploy your documentation site Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding process. During onboarding, you'll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments. @@ -75,7 +73,6 @@ Find your exact URL on the **Overview** page of your [dashboard](https://app.min ``` ```bash pnpm - pnpm add -g mint ```