diff --git a/agent/slack.mdx b/agent/slack.mdx index 9d8f50ba5..cdba8e12d 100644 --- a/agent/slack.mdx +++ b/agent/slack.mdx @@ -34,7 +34,7 @@ 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. +After you connect your Slack workspace, 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: @@ -46,7 +46,7 @@ To add a new integration from Slack: 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. +Integrations that you connect from Slack apply 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. @@ -96,7 +96,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 diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx index 834aa3f6b..1a7670a07 100644 --- a/ai/mintlify-mcp.mdx +++ b/ai/mintlify-mcp.mdx @@ -20,7 +20,7 @@ Connect any MCP client like Claude, Claude Code, or Cursor to the Mintlify MCP t | :-- | :-- | :-- | | **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 | +| **Endpoints** | `/mcp` on your site domain | Hosted by Mintlify, scoped to your project | | **Output** | Search results and page content | Content edits, navigation changes, pull requests | ## Connect to the Mintlify MCP diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index b5dec89f9..d9ab9c4d0 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -48,7 +48,7 @@ Your MCP server also exposes your [skill.md files](/ai/skillmd) as MCP resources 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. +- **`scoreThreshold`**: Minimum relevance score between 0 and 1. Returns only results at or above this score. 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. diff --git a/api/agent/v2/create-agent-job.mdx b/api/agent/v2/create-agent-job.mdx index b48a847d4..ef6cd683c 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 ecae62342..6fcc6650a 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 abbc26e36..06663c457 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 5a4902688..377fd12c2 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/preview/trigger.mdx b/api/preview/trigger.mdx index aa5a76d05..cf9d1fed5 100644 --- a/api/preview/trigger.mdx +++ b/api/preview/trigger.mdx @@ -15,7 +15,7 @@ The response includes a `statusId` that you can pass to [Get deployment status]( ## 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/index.mdx b/assistant/index.mdx index 920fb06ea..ec1905aa2 100644 --- a/assistant/index.mdx +++ b/assistant/index.mdx @@ -6,7 +6,7 @@ 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 available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=assistant) and enabled by default for those plans. ## About the assistant diff --git a/components/frames.mdx b/components/frames.mdx index 6f598336b..d0473eba5 100644 --- a/components/frames.mdx +++ b/components/frames.mdx @@ -21,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. @@ -33,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. @@ -54,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 6dbd1fe10..9421adb1e 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -17,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/tiles.mdx b/components/tiles.mdx index 57d8828ca..a7d02920b 100644 --- a/components/tiles.mdx +++ b/components/tiles.mdx @@ -58,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/view.mdx b/components/view.mdx index d065d6bbb..4eb57ea86 100644 --- a/components/view.mdx +++ b/components/view.mdx @@ -12,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!"); @@ -20,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!") @@ -31,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!"); @@ -39,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 3b97d8157..84964fded 100644 --- a/components/visibility.mdx +++ b/components/visibility.mdx @@ -25,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. > @@ -48,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/create/files.mdx b/create/files.mdx index d0f742766..660744f54 100644 --- a/create/files.mdx +++ b/create/files.mdx @@ -23,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/customize/custom-domain.mdx b/customize/custom-domain.mdx index e60705f29..512390331 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -46,18 +46,18 @@ 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. + 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 Mintlify issues certificates causes HTTPS requests to fail until provisioning completes. ### 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). -Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after your TLS certificate is provisioned. +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 TXT records are added and your DNS records resolve correctly, a free SSL/TLS certificate is automatically generated for your site 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,13 +71,13 @@ 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 Vercel is your domain provider, you must add a verification `TXT` record. This information appears on your dashboard after submitting your custom domain, and Mintlify emails it to you. diff --git a/deploy/cloudflare.mdx b/deploy/cloudflare.mdx index 3a6631376..26c80b964 100644 --- a/deploy/cloudflare.mdx +++ b/deploy/cloudflare.mdx @@ -10,7 +10,7 @@ import Propagating from "/snippets/custom-subpath-propagating.mdx"; To host your documentation at a subpath such as `yoursite.com/docs` using Cloudflare, you must create and configure a Cloudflare Worker. - Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare). + Before you begin, you need a Cloudflare account and a domain name (managed on or off Cloudflare). ## Set up a worker @@ -113,7 +113,7 @@ See [Add a custom domain](https://developers.cloudflare.com/workers/configuratio ### Resolve DNS conflicts -If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must be configured to control all traffic for your domain. +If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must control all traffic for your domain. 1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information. 2. Return to your Worker and add your custom domain. diff --git a/deploy/deployments.mdx b/deploy/deployments.mdx index 87fbb44fb..11f3293d8 100644 --- a/deploy/deployments.mdx +++ b/deploy/deployments.mdx @@ -44,4 +44,4 @@ You can permanently delete a deployment from the [Danger zone](https://dashboard Deleting a deployment is permanent and cannot be undone. If you have an active subscription, you'll receive a prorated credit for any unused time remaining in your billing period. -If you have multiple deployments, you'll be redirected to another deployment after deletion. If you delete your only deployment, you'll be redirected to the Mintlify homepage. When you delete a deployment, the organization admin receives an email notification confirming the deletion. +If you have multiple deployments, Mintlify redirects you to another deployment after deletion. If you delete your only deployment, Mintlify redirects you to the Mintlify homepage. When you delete a deployment, the organization admin receives an email notification confirming the deletion. diff --git a/deploy/github.mdx b/deploy/github.mdx index 0724faf29..32957cf7d 100644 --- a/deploy/github.mdx +++ b/deploy/github.mdx @@ -51,9 +51,9 @@ If you skipped connecting your own Git repository during onboarding, your docume -After completing either path, install the GitHub App by following the steps in [Install the GitHub App](#install-the-github-app). +After completing either path, install the GitHub app by following the steps in [Install the GitHub app](#install-the-github-app). -## Install the GitHub App +## Install the GitHub app You must have organization ownership or administrator permissions in a repository to install the app. If you lack the necessary permissions, the repository owner must approve the installation request. @@ -127,7 +127,7 @@ If pushes to your repository don't trigger deployments, check the following poss -### GitHub App connection issues +### GitHub app connection issues If you encounter problems with the GitHub app, resetting the connection can solve most problems. diff --git a/deploy/vercel.mdx b/deploy/vercel.mdx index 08819b9b1..426ca6618 100644 --- a/deploy/vercel.mdx +++ b/deploy/vercel.mdx @@ -29,7 +29,7 @@ Rewrites map incoming requests to different destinations without changing the UR 3. Enter your domain. 4. Select **Add domain**. -5. Add the following rewrites to your `vercel.json` file. Replace `[subdomain]` with your subdomain, which is found at the end of your dashboard URL. For example, `dashboard.mintlify.com/your-organization/your-subdomain` has a domain identifier of `your-subdomain`. +5. Add the following rewrites to your `vercel.json` file. Replace `[subdomain]` with your subdomain, which appears at the end of your dashboard URL. For example, `dashboard.mintlify.com/your-organization/your-subdomain` has a domain identifier of `your-subdomain`. ```json { @@ -56,7 +56,7 @@ For more information, see [Configuring projects with vercel.json: Rewrites](http ### Host at custom subpath -To use a custom subpath (any path other than `/docs`), you must organize your documentation files within your repository to match your subpath structure. For example, if your documentation is hosted at `yoursite.com/help`, your documentation files must be in a `help/` directory. +To use a custom subpath (any path other than `/docs`), you must organize your documentation files within your repository to match your subpath structure. For example, if you host your documentation at `yoursite.com/help`, your documentation files must be in a `help/` directory. Use the generator below to create your rewrites configuration. Add the rewrites to your `vercel.json` file. diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx index ef87ff7a8..81a4294e0 100644 --- a/editor/branching-and-publishing.mdx +++ b/editor/branching-and-publishing.mdx @@ -10,7 +10,7 @@ What happens when you publish depends on two things: **which branch you're on** ## Saving versus publishing -**Saving** happens automatically. Your edits are stored on Mintlify's servers and persist across browser tabs, devices, and network interruptions. +**Saving** happens automatically. Mintlify stores your edits on its servers and persists them across browser tabs, devices, and network interruptions. **Publishing** commits your changes to your Git repository. Click the **Publish** button in the toolbar to open the publish menu, save your changes as a Git commit, and create a pull request. @@ -38,7 +38,7 @@ The actions available when you click the publish button depend on your current b - **Create branch**: Moves your pending changes to a new feature branch when you're on a protected deployment branch. - **Create pull request**: Opens a pull request targeting your deployment branch. -If there are no pending changes, the publish and save actions are disabled. +If there are no pending changes, the editor disables the publish and save actions. Your live site updates after Mintlify builds and deploys your changes. This typically takes 30 seconds to a few minutes. Check the deployment status on your [dashboard](https://dashboard.mintlify.com). @@ -48,7 +48,7 @@ If there are no pending changes, the publish and save actions are disabled. **Edit directly on your deployment branch** if you do not use a Git-based workflow. -**Create a branch** when you use a docs-as-code workflow where each change to your content is made on a separate branch. +**Create a branch** when you use a docs-as-code workflow where you make each change to your content on a separate branch. ## Create and switch branches @@ -70,7 +70,7 @@ If there are no pending changes, the publish and save actions are disabled. 1. Click the branch to switch to it. - Switching branches while you have unpublished changes will prompt you to bring those changes to the new branch or leave them behind. Changes left behind remain on your original branch. + Switching branches while you have unpublished changes prompts you to bring those changes to the new branch or leave them behind. Changes left behind remain on your original branch. @@ -112,13 +112,13 @@ For example: `https://dashboard.mintlify.com/acme/docs/editor/main/~/guides/quic When a pull request is open for the current branch, the publish menu shows its review status: -- **Approved**: The pull request has been approved and is ready to merge. +- **Approved**: A reviewer approved the pull request and it is ready to merge. - **Changes requested**: A reviewer has requested changes before the pull request can merge. - **Awaiting review**: The pull request is waiting for a reviewer. Click **View request** to open the pull request in your Git provider. -When the pull request is approved, click **Merge and publish** to merge and deploy directly from the editor. The editor switches to your deployment branch after merging. +After a reviewer approves the pull request, click **Merge and publish** to merge and deploy directly from the editor. The editor switches to your deployment branch after merging. Configure branch protection rules in your Git provider to require pull requests. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) in the GitHub docs or [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/) in the GitLab docs. diff --git a/editor/configurations.mdx b/editor/configurations.mdx index 704098954..58ca67a58 100644 --- a/editor/configurations.mdx +++ b/editor/configurations.mdx @@ -75,7 +75,7 @@ Customize how content appears on your site. - **Thumbnail background**: Set a custom background image for page thumbnails and social previews. - **Thumbnail appearance**: Control how thumbnails display. - **Thumbnail font**: Set a custom font for text in thumbnails. -- **Page eyebrow**: Add small labels above page titles. +- **Page eyebrow**: Add small labels preceding page titles. - **Code block theme**: Choose the syntax highlighting theme for code blocks. - **LaTeX support**: Enable mathematical notation rendering with LaTeX. - **Icon library**: Choose the icon library to use for your site. @@ -84,7 +84,7 @@ Customize how content appears on your site. Customize the search experience. -- **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...". +- **Search placeholder**: The text that appears in the search box before users type. Default is `Search or ask`. ## Connect integrations diff --git a/editor/git-essentials.mdx b/editor/git-essentials.mdx index d11bc9310..3133c1e02 100644 --- a/editor/git-essentials.mdx +++ b/editor/git-essentials.mdx @@ -52,7 +52,7 @@ These are the Git concepts you'll encounter most often when using the web editor Occurs when two branches have incompatible changes to the same files. The editor helps you resolve conflicts when they occur. - A comparison showing the differences between two versions of a file. The editor shows a visual diff of your pending changes before you publish so you can review exactly what will be committed. + A comparison showing the differences between two versions of a file. The editor shows a visual diff of your pending changes before you publish so you can review exactly what gets committed. diff --git a/editor/pages.mdx b/editor/pages.mdx index d087f1014..c97a43705 100644 --- a/editor/pages.mdx +++ b/editor/pages.mdx @@ -9,7 +9,7 @@ keywords: ["editor", "content", "pages", "files", "create", "edit", "media", "im Browse pages in the **Navigation** tab of the left panel. Click a page to open it. Click the search icon or press Cmd + K (macOS) or Ctrl + K (Windows) to search by filename or page content. - API specification files (OpenAPI and AsyncAPI) are read-only in the web editor. To update a spec file, edit it in your preferred code editor and push the changes to your documentation repository. + The web editor treats API specification files (OpenAPI and AsyncAPI) as read-only. To update a spec file, edit it in your preferred code editor and push the changes to your documentation repository. ## Create new pages @@ -36,7 +36,7 @@ Switch between visual and Markdown mode with the toggle in the toolbar. **Markdown mode** gives you direct access to the MDX source. Use it for precise control over component properties and frontmatter. - API specification files (OpenAPI and AsyncAPI) are read-only in the web editor. Edit them in your code editor and push the changes to your repository. + The web editor treats API specification files (OpenAPI and AsyncAPI) as read-only. Edit them in your code editor and push the changes to your repository. For a full list of components, see [Components](/components). For MDX syntax, see [Format text](/create/text) and [Format code](/create/code). @@ -62,7 +62,7 @@ In visual mode, the editor shows a minimap on the right side of the page that re When editing a code block in visual mode, you can: -- **Highlight or focus lines**: Select text within the code block, then use the toolbar that appears to mark lines as highlighted or focused. Highlighted lines are visually emphasized; focused lines dim everything else. +- **Highlight or focus lines**: Select text within the code block, then use the toolbar that appears to mark lines as highlighted or focused. Highlighting visually emphasizes lines. Focusing lines dims everything else. - **Mark diff lines**: Select lines and use the toolbar to mark them as additions (`+`) or removals (`-`). - **Wrap**: Toggle line wrapping in the code block settings. - **Expandable**: Make the code block collapsible so readers can expand it on demand. @@ -78,11 +78,11 @@ Diff view is read-only. Click the button next to the mode togg - **Move**: Drag and drop pages to reorder them in navigation. - **Rename**: Right-click a page and select **Rename**. - **Duplicate**: Right-click a page and select **Duplicate**. -- **Delete**: Right-click a page and select **Delete**. The page is removed from navigation automatically. +- **Delete**: Right-click a page and select **Delete**. The editor removes the page from navigation automatically. ### Pages deleted via Git -If a teammate deletes a page through Git while you have it open, the editor enters read-only mode and shows a banner. Your content is preserved so you can copy it before navigating away. +If a teammate deletes a page through Git while you have it open, the editor enters read-only mode and shows a banner. The editor preserves your content so you can copy it before navigating away. ## Configure pages diff --git a/editor/share-a-preview.mdx b/editor/share-a-preview.mdx index 4fbc5f4fd..509d2f2ef 100644 --- a/editor/share-a-preview.mdx +++ b/editor/share-a-preview.mdx @@ -6,7 +6,7 @@ keywords: ["editor", "preview", "preview deployment", "share", "collaboration", ## Preview deployments -Every time you save changes to a feature branch, Mintlify builds a preview deployment — a temporary URL where your changes are rendered exactly as they'll look when published. Use it to review your work or collect feedback before merging. +Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL that renders your changes exactly as they look when published. Use it to review your work or collect feedback before merging. ### Access your preview @@ -15,7 +15,7 @@ Every time you save changes to a feature branch, Mintlify builds a preview deplo ### Share your preview -Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch — no need to reshare. +Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch. ### Restrict access to previews diff --git a/editor/tutorial.mdx b/editor/tutorial.mdx index c2d8ad613..329e9c312 100644 --- a/editor/tutorial.mdx +++ b/editor/tutorial.mdx @@ -39,7 +39,7 @@ This tutorial walks you through a complete content update using the editor. You' - To review your changes, you must create a pull request. A pull request is a proposal to merge your changes into the main branch that your site is built from. + To review your changes, you must create a pull request. A pull request is a proposal to merge your changes into the main branch that builds your site. When you publish your branch, you make it available for review by your team. The changes only appear on your live site if you merge the pull request. @@ -58,6 +58,6 @@ This tutorial walks you through a complete content update using the editor. You' Share your pull request with your team to review your changes. - When your changes are approved, merge your pull request into the main branch. Your changes deploy to your live site. + After your team approves your changes, merge your pull request into the main branch. Your changes deploy to your live site. diff --git a/guides/improving-docs.mdx b/guides/improving-docs.mdx index 8ad97fd7d..dcbaac8f9 100644 --- a/guides/improving-docs.mdx +++ b/guides/improving-docs.mdx @@ -41,7 +41,7 @@ Combine bounce rate with feedback scores to interpret it correctly. High bounce Mintlify's analytics lets you see feedback scores alongside traffic data. Use this to prioritize: - **High traffic, low satisfaction:** Popular pages with a poor user experience. Fix these first—they affect the most users. -- **Low traffic, high satisfaction:** Content that works but isn't being found. Check whether navigation and internal links are directing users there. +- **Low traffic, high satisfaction:** Content that works but users aren't finding. Check whether navigation and internal links direct users there. - **High traffic, high satisfaction:** Your best-performing pages. Review them for patterns to apply elsewhere. ## Collect qualitative feedback @@ -114,7 +114,7 @@ Monthly for high-traffic pages and overall satisfaction trends. Quarterly for a -Look at the page analytically. High time on page combined with negative ratings often means users are struggling to follow instructions. Low time combined with negative ratings often means users didn't find what they were looking for. Cross-reference with support ticket topics for that page to get more specific signal. When you can't diagnose the problem from data, a short user interview session will answer it quickly. +Look at the page analytically. High time on page combined with negative ratings often means users are struggling to follow instructions. Low time combined with negative ratings often means users didn't find what they were looking for. Cross-reference with support ticket topics for that page to get more specific signal. When you can't diagnose the problem from data, a short user interview session usually answers it quickly. diff --git a/guides/maintenance.mdx b/guides/maintenance.mdx index 52d21eb46..bc45efcd9 100644 --- a/guides/maintenance.mdx +++ b/guides/maintenance.mdx @@ -47,7 +47,7 @@ For content not tied to a specific feature, scheduled reviews catch accumulating Manually tracking review dates across hundreds of pages doesn't scale. Automate what you can: -- Flag pages that haven't been updated in over 90 days for a review +- Flag pages without updates in over 90 days for review - Monitor search analytics for queries that return no results—these often signal content that should exist but doesn't - Use [CI checks](/deploy/ci) to enforce frontmatter requirements and catch broken links on every pull request @@ -61,8 +61,8 @@ Automation can't replace editorial judgment, but it reduces the manual work requ - **Broken links:** Run `mint broken-links` before publishing to catch broken internal and external links before users encounter them. - **Style enforcement:** A linter like [Vale](https://vale.sh) checks prose against configurable rules—terminology consistency, passive voice, missing punctuation—on every pull request. See [Style and tone](/guides/style-and-tone) for more on linting. -- **API reference updates:** If your API reference is generated from an OpenAPI specification, automate spec generation as part of your release pipeline so the reference never falls behind. -- **Automated documentation drafts:** Use the [agent API](/guides/automate-agent) to automatically generate documentation drafts when code is merged. +- **API reference updates:** If you generate your API reference from an OpenAPI specification, automate spec generation as part of your release pipeline so the reference never falls behind. +- **Automated documentation drafts:** Use the [agent API](/guides/automate-agent) to automatically generate documentation drafts when teammates merge code. ## Know when to rewrite @@ -72,13 +72,13 @@ Signs a page needs a rewrite rather than edits: - Users consistently report confusion despite multiple rounds of editing - The page has grown to cover multiple distinct topics that should be separate pages - The product has changed so fundamentally that the page's structure no longer maps to how the feature works -- More than half the content is edge cases, caveats, or "this doesn't apply if..." +- More than half the content is edge cases, caveats, or "this doesn't apply if" exceptions A rewrite is less daunting when you start with a structured audit: document what's missing, what's misleading, and what's redundant before writing anything. Complete rewrites in focused sprints rather than trying to do everything at once. ## Remove what no longer belongs -Wrong documentation is worse than no documentation. Users who follow inaccurate steps waste time and lose confidence in your product and your team. When content is completely inaccurate and can't be fixed immediately, remove it rather than leaving it up. +Wrong documentation is worse than no documentation. Users who follow inaccurate steps waste time and lose confidence in your product and your team. When content is completely inaccurate and you can't fix it immediately, remove it rather than leaving it up. When removing content: - Set up a redirect from the old URL to the most relevant current page @@ -93,7 +93,7 @@ Make it a required step, not a request. Include documentation in your definition -Keep deprecated documentation accessible but clearly marked. Add a notice at the top of the page indicating that the feature is deprecated, when it will be removed, and what users should migrate to. Don't delete the page until the feature is actually removed—users on older versions still need it. Once removed, redirect the URL to the migration guide or the replacement feature's documentation. +Keep deprecated documentation accessible but clearly marked. Add a notice at the top of the page indicating that the team has deprecated the feature, when it goes away, and what users should migrate to. Don't delete the page until you actually remove the feature—users on older versions still need it. After removal, redirect the URL to the migration guide or the replacement feature's documentation. diff --git a/guides/navigation.mdx b/guides/navigation.mdx index 1d859eebd..cf2a5bf72 100644 --- a/guides/navigation.mdx +++ b/guides/navigation.mdx @@ -22,7 +22,7 @@ Questions to ask: - What are the product's core building blocks? - How do users typically adopt the product? Where do they most often get stuck? - What are the most important integrations or dependencies? -- If the product was broken into different layers, what would they be? Would it be organized by tasks people perform or by features they use? +- If you broke the product into different layers, what would they be? Would you organize it by tasks people perform or by features they use? These conversations surface the natural structure of the product and often reveal where documentation navigation has drifted from how users actually think. @@ -130,7 +130,7 @@ User goals, in most cases. Feature-based navigation makes sense for product team -Aim for 5–7. Research on cognitive load suggests users can comfortably evaluate about 7 items before decision fatigue sets in. If you have more, look for natural groupings that can be combined into a single section with subsections. +Aim for 5–7. Research on cognitive load suggests users can comfortably evaluate about 7 items before decision fatigue sets in. If you have more, look for natural groupings that you can combine into a single section with subsections. diff --git a/guides/seo.mdx b/guides/seo.mdx index b904580ac..99cfc5bc9 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -25,9 +25,9 @@ Write titles that match how users search, not how your product UI labels things. The description appears below your page title in search results. A good description improves click-through rates even when rankings are equal. -- Summarize what users will accomplish, not just what the page covers +- Summarize what users can accomplish, not just what the page covers - Include the primary keyword naturally -- Write in active voice: "Learn how to configure..." not "This page explains..." +- Write in active voice: "Learn how to configure" rather than "This page explains" Mintlify generates meta tags automatically from your `title` and `description` frontmatter. For advanced configuration like Open Graph images, canonical URLs, or custom robots directives, see the [SEO configuration reference](/optimize/seo). @@ -69,7 +69,7 @@ Mintlify creates the H1 for each page automatically from the `title:` property i | Rate limits | Understanding API rate limits | | Configuration | How to configure your integration | -Headings written as questions are more likely to appear in Google's People Also Ask boxes, which appear above organic results and generate clicks even from lower-ranked pages. +Headings written as questions are more likely to appear in Google's People Also Ask boxes, which appear before organic results and generate clicks even from lower-ranked pages. ## Build internal links between related pages diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index d74650f0f..9b96e3034 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -41,7 +41,7 @@ A quick test: if you can add "by zombies" after the verb, the sentence is passiv ## Keep sentences and paragraphs short -Documentation is scanned more than it's read. Long sentences and dense paragraphs slow users down when they're trying to find a specific answer. +Users scan documentation more than they read it. Long sentences and dense paragraphs slow users down when they're trying to find a specific answer. Guidelines: - Aim for sentences under 25 words @@ -49,7 +49,7 @@ Guidelines: - Two to four sentences per paragraph - Break up lists of steps with numbered sequences, not run-on prose -If a sentence requires multiple commas or semicolons to hold together, it can probably be split into two sentences. +If a sentence requires multiple commas or semicolons to hold together, you can probably split it into two sentences. ## Use headings that match user intent @@ -65,7 +65,7 @@ Headings organize the page for both humans and search engines. Write them to ans Use sentence case for all headings ("Getting started," not "Getting Started"). Don't skip heading levels—go from H2 to H3, not H2 to H4. -In Mintlify docs, the page's H1 is generated automatically from the `title:` frontmatter property. Don't add a manual H1 in the body. +In Mintlify docs, the page's H1 generates automatically from the `title:` frontmatter property. Don't add a manual H1 in the body. ## Use consistent terminology diff --git a/integrations/analytics/posthog.mdx b/integrations/analytics/posthog.mdx index 5b62c76ec..61cdd4ebf 100644 --- a/integrations/analytics/posthog.mdx +++ b/integrations/analytics/posthog.mdx @@ -47,7 +47,7 @@ You only need to include `apiHost` if you are self-hosting PostHog. We send even ## Session recordings -Session recordings are enabled by default when you configure PostHog. To disable session recordings while keeping analytics enabled, set `sessionRecording` to `false` in your configuration. +Configuring PostHog enables session recordings by default. To disable session recordings while keeping analytics enabled, set `sessionRecording` to `false` in your configuration. ```json Disable session recordings "integrations": { diff --git a/optimize/feedback.mdx b/optimize/feedback.mdx index 4208e38b5..132e60ea1 100644 --- a/optimize/feedback.mdx +++ b/optimize/feedback.mdx @@ -82,7 +82,7 @@ Best practices for setting feedback statuses: - **Pending**: Feedback is awaiting review. - **In Progress**: Work is in progress to address the feedback. -- **Resolved**: Feedback has been resolved. +- **Resolved**: You resolved the feedback. - **Dismissed**: Feedback is irrelevant or inaccurate. ### Filter by status diff --git a/workflows/manage.mdx b/workflows/manage.mdx index 35be8fc61..0064a7580 100644 --- a/workflows/manage.mdx +++ b/workflows/manage.mdx @@ -1,6 +1,6 @@ --- title: "Manage workflows" -description: "Trigger, disable, re-enable, and delete Mintlify workflows from your dashboard, and learn how schedules recalculate after a workflow is paused and resumed." +description: "Trigger, disable, re-enable, and delete Mintlify workflows from your dashboard, and learn how schedules recalculate after you pause and resume a workflow." keywords: ["manage workflows", "trigger workflow", "disable workflow", "enable workflow"] ---