From a296ca7a92ef88f892bf6851f6122750e2d56d48 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:01:48 -0700 Subject: [PATCH 01/13] don't lint inside JSON examples --- .vale.ini | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 9c3a813f9..ef652b642 100644 --- a/.vale.ini +++ b/.vale.ini @@ -25,6 +25,7 @@ TokenIgnores = (?sm)((?:import|export) .+?$), \ (<[A-Z]\w+>.+?<\/[A-Z]\w+>) BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({.+.*}) +(?sm)^({.+.*}), \ +(?sm)^```json\n.*?\n```$ CommentDelimiters = {/*, */} \ No newline at end of file From 5639f00f06620965dd1e0731ec8c0489324cb55d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:04:06 -0700 Subject: [PATCH 02/13] actually don't lint inside JSON snippets --- .vale.ini | 3 +-- .vale/styles/Google/Quotes.yml | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.vale.ini b/.vale.ini index ef652b642..9c3a813f9 100644 --- a/.vale.ini +++ b/.vale.ini @@ -25,7 +25,6 @@ TokenIgnores = (?sm)((?:import|export) .+?$), \ (<[A-Z]\w+>.+?<\/[A-Z]\w+>) BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({.+.*}), \ -(?sm)^```json\n.*?\n```$ +(?sm)^({.+.*}) CommentDelimiters = {/*, */} \ No newline at end of file diff --git a/.vale/styles/Google/Quotes.yml b/.vale/styles/Google/Quotes.yml index 3cb6f1abd..3f418f4d5 100644 --- a/.vale/styles/Google/Quotes.yml +++ b/.vale/styles/Google/Quotes.yml @@ -4,4 +4,5 @@ link: 'https://developers.google.com/style/quotation-marks' level: error nonword: true tokens: - - '"[^"]+"[.,?]' + # Match quotes with trailing punctuation, but exclude patterns that look like JSON/code + - '(? Date: Fri, 19 Sep 2025 17:05:34 -0700 Subject: [PATCH 03/13] update vocab --- .vale/styles/Google/Quotes.yml | 2 +- .vale/styles/config/vocabularies/Mintlify/accept.txt | 10 +++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.vale/styles/Google/Quotes.yml b/.vale/styles/Google/Quotes.yml index 3f418f4d5..d7161c5c7 100644 --- a/.vale/styles/Google/Quotes.yml +++ b/.vale/styles/Google/Quotes.yml @@ -4,5 +4,5 @@ link: 'https://developers.google.com/style/quotation-marks' level: error nonword: true tokens: - # Match quotes with trailing punctuation, but exclude patterns that look like JSON/code + # Match quotes with trailing punctuation, but exclude like JSON - '(? Date: Fri, 19 Sep 2025 17:05:39 -0700 Subject: [PATCH 04/13] fix errors --- advanced/dashboard/sso.mdx | 4 ++-- advanced/subpath/route53-cloudfront.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/advanced/dashboard/sso.mdx b/advanced/dashboard/sso.mdx index 5214b9267..400ca2017 100644 --- a/advanced/dashboard/sso.mdx +++ b/advanced/dashboard/sso.mdx @@ -45,7 +45,7 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta, Google Once the application is set up, navigate to the General tab and locate the client ID & client secret. - Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. + Please securely provide us with these, along with your Okta instance URL (for example, `.okta.com`). You can send these via a service like 1Password or SendSafely. @@ -97,7 +97,7 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta, Google - 1. Under "Enterprise applications", select **New application**. + 1. Under "Enterprise applications," select **New application**. 2. Select **Create your own application** and choose "Integrate any other application you don't find in the gallery (Non-gallery)." diff --git a/advanced/subpath/route53-cloudfront.mdx b/advanced/subpath/route53-cloudfront.mdx index a39be3c41..bcd6589e0 100644 --- a/advanced/subpath/route53-cloudfront.mdx +++ b/advanced/subpath/route53-cloudfront.mdx @@ -70,7 +70,7 @@ All Behaviors must have the an **origin request policy** of `AllViewerExceptHost If you use Vercel, use the `.vercel.app` domain available for every project. -3. Create a new Origin and add your staging URL as the "Origin domain". +3. Create a new Origin and add your staging URL as the "Origin domain." ![CloudFront "Create origin" page with a "Origin domain" input field highlighted.](/images/cloudfront/default-origin.png) @@ -101,7 +101,7 @@ Behaviors in CloudFront enable control over the subpath logic. At a high level, Create behaviors for Vercel domain verification paths with a **Path pattern** of `/.well-known/*` and set **Origin and origin groups** to your docs URL. -For "Cache policy", select **CachingDisabled** to ensure these verification requests pass through without caching. +For "Cache policy," select **CachingDisabled** to ensure these verification requests pass through without caching. ![CloudFront "Create behavior" page with a "Path pattern" of "/.well-known/*" and "Origin and origin groups" pointing to the staging URL.](/images/cloudfront/well-known-policy.png) From b4b8ca49d15f1cfcf4b303bf701bcae24c0edb55 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:12:55 -0700 Subject: [PATCH 05/13] update vocab --- .../config/vocabularies/Mintlify/accept.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index f342a6eb0..984d48851 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -41,8 +41,13 @@ Babel babel Bitbucket chatgpt +ChatGPT +claude +Claude Chromium CircleCI +Clearbit +Ctrl Cypress Django DynamoDB @@ -62,6 +67,7 @@ Go Golang GraphQL Heroku +Hightouch IntelliJ Java JavaScript @@ -72,18 +78,26 @@ Kotlin Kubernetes Laravel Linux +LLMs macOS +mcp +MCP MDX +Mixpanel Mocha MongoDB MySQL Next.js Node.js NodeJS +npx Nuxt OAuth Okta +Osano +Pirsch PNPM +Posthog Postman PostgreSQL Prettier @@ -109,6 +123,7 @@ Vite vite Visual Studio Code VS Code +vscode Vue Vuex Webflow From be83a849b54ea9ab728eb8d2c1fb4c2b82abb9af Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:13:16 -0700 Subject: [PATCH 06/13] remove latin abbreviations --- changelog.mdx | 6 +++--- components/cards.mdx | 2 +- guides/auth0.mdx | 4 ++-- image-embeds.mdx | 2 +- installation.mdx | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/changelog.mdx b/changelog.mdx index 8a0e11113..45b452f2a 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -184,7 +184,7 @@ noindex: true ## API playground enhancements - New [Search API endpoint](https://mintlify.com/docs/api-reference/assistant/search) so you can build agents and MCP servers on top of your docs - - `openapi` and `asyncapi` files are now served at their specified paths (e.g. `https://mydocsurl.extension/{openapi-or-file-name}.json`) + - `openapi` and `asyncapi` files are now served at their specified paths (for example, `https://mydocsurl.extension/{openapi-or-file-name}.json`) - You can now use the [`x-mint` field in your openapi files](https://mintlify.com/docs/api-playground/openapi-setup#x-mint-extension) to override generated fields, customize preface content, or change endpoint URLs in code samples - [`x-mcp` is now `x-mint.mcp`](https://mintlify.com/docs/api-playground/openapi-setup#mcp) in OpenAPI configurations to control which routes are exposed as MCP tools @@ -426,7 +426,7 @@ noindex: true ## AI Assistant Improvements - New UI with dedicated chat page & pre-filled prompts - - Stability improvements, e.g. bug fixes of editing the wrong file or no files at all + - Stability improvements. For example, bug fixes of editing the wrong file or no files at all - More robust knowledge for adding & editing components - Improved `docs.json` file editing @@ -439,7 +439,7 @@ noindex: true We’ve overhauled the design and performance of the [API Playground](/api-playground/). Updates include: - Easier detail expansion for an overview of a field - - More intuitive nested design, e.g. adding or deleting items + - More intuitive nested design. For example, adding or deleting items - Faster response times ## Quality Improvements diff --git a/components/cards.mdx b/components/cards.mdx index 87323c823..db1151f79 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -107,7 +107,7 @@ Use the [Columns component](/components/columns) to organize multiple cards side - Icon color as a hex code (e.g., `#FF6B6B`). + Icon color as a hex code (for example, `#FF6B6B`). diff --git a/guides/auth0.mdx b/guides/auth0.mdx index 2d3b6843e..f976c7e13 100644 --- a/guides/auth0.mdx +++ b/guides/auth0.mdx @@ -13,7 +13,7 @@ This guide walks you through setting up Auth0 as an authentication provider for - Log in to your Auth0 dashboard and navigate to **Applications** > **Applications**. Click the **Create Application** button, give your application a name (e.g., "Mintlify"), and select **Regular Web Applications** as the application type. Then click **Create**. + Log in to your Auth0 dashboard and navigate to **Applications** > **Applications**. Click the **Create Application** button, give your application a name (for example, "Mintlify"), and select **Regular Web Applications** as the application type. Then click **Create**. ![Creating a new application in Auth0](/images/guides/auth0/auth0-create-application.png) @@ -23,7 +23,7 @@ This guide walks you through setting up Auth0 as an authentication provider for ![Auth0 client settings page](/images/guides/auth0/auth0clientsettings.png) Make note of the following information: - - **Domain**: This is your Auth0 tenant domain (e.g., `your-tenant.auth0.com`) + - **Domain**: This is your Auth0 tenant domain (for example, `your-tenant.auth0.com`) - **Client ID**: The public identifier for your application - **Client Secret**: The secret key for your application (keep this secure) diff --git a/image-embeds.mdx b/image-embeds.mdx index 700030a79..3725e0d14 100644 --- a/image-embeds.mdx +++ b/image-embeds.mdx @@ -32,7 +32,7 @@ Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows. -Image files must be less than 20MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com). +Image files must be less than 20 MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com). ### HTML image embeds diff --git a/installation.mdx b/installation.mdx index 988d4e196..69a05574f 100644 --- a/installation.mdx +++ b/installation.mdx @@ -116,7 +116,7 @@ You can use the CLI to check your OpenAPI file for errors using the following co mint openapi-check ``` -You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`). +You can pass in a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`). ### Renaming files From 0b3f0b3335060cdb4759261ab55014a064bb26f0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:15:05 -0700 Subject: [PATCH 07/13] don't lint snippets --- .vale.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale.ini b/.vale.ini index 9c3a813f9..4c34ecadd 100644 --- a/.vale.ini +++ b/.vale.ini @@ -4,6 +4,7 @@ StylesPath = .vale/styles MinAlertLevel = suggestion IgnoredScopes = code, tt, img, url, a SkippedScopes = script, style, pre, figure, code +IgnoredFiles = snippets/** Packages = Google From 40d8d6f12027bf30524cd744d82b59e9483856eb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:15:14 -0700 Subject: [PATCH 08/13] update vocab --- .vale/styles/config/vocabularies/Mintlify/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index 984d48851..68c650a0c 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -164,6 +164,7 @@ enum env err func +frontmatter gui href html From 58b7ca670fed4f90aed1715a6baf3e28fc62eb81 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:18:40 -0700 Subject: [PATCH 09/13] don't lint in angle brackets --- .vale.ini | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.vale.ini b/.vale.ini index 4c34ecadd..febeefd3b 100644 --- a/.vale.ini +++ b/.vale.ini @@ -4,7 +4,6 @@ StylesPath = .vale/styles MinAlertLevel = suggestion IgnoredScopes = code, tt, img, url, a SkippedScopes = script, style, pre, figure, code -IgnoredFiles = snippets/** Packages = Google @@ -23,7 +22,8 @@ Vale.Avoid = NO # Too aggressive about common technical terms # Token and block ignores for MDX-specific syntax TokenIgnores = (?sm)((?:import|export) .+?$), \ (?)(?!`), \ -(<[A-Z]\w+>.+?<\/[A-Z]\w+>) +(<[A-Z]\w+>.+?<\/[A-Z]\w+>), \ +(<[^>]*>) BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ (?sm)^({.+.*}) From fcbc12cf42096a643489c4976c84da30b33b96de Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:18:48 -0700 Subject: [PATCH 10/13] add language tags --- .vale/styles/config/vocabularies/Mintlify/accept.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index 68c650a0c..cd736fec0 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -241,3 +241,10 @@ xhr2 yaml yarn yml + +# ============================================================================= +# LOCALIZATION +# ============================================================================= +cn +ko +ru \ No newline at end of file From d30c8bd59bd09f3d92524f00b9e3e115f1c9b9f9 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:23:42 -0700 Subject: [PATCH 11/13] update vocab --- .../config/vocabularies/Mintlify/accept.txt | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index cd736fec0..d9e20502c 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -42,8 +42,9 @@ babel Bitbucket chatgpt ChatGPT -claude Claude +claude +CloudFront Chromium CircleCI Clearbit @@ -79,6 +80,7 @@ Kubernetes Laravel Linux LLMs +Lucide macOS mcp MCP @@ -131,14 +133,18 @@ WebKit Webpack webpack WebStorm +Zapier # ============================================================================= # TERMS # ============================================================================= +agentic allowlist APIs args async +autogenerated +autogenerating await bool boolean @@ -163,8 +169,10 @@ elem enum env err +favicons func frontmatter +Gantt gui href html @@ -172,6 +180,7 @@ http https ide impl +ingestible init instanceof jvm @@ -183,6 +192,7 @@ md middleware Multiline mvc +monorepo nav next nodejs @@ -207,7 +217,9 @@ res rpc runtime scss +SDKs sdk +serverless Singleline sql ssh @@ -218,16 +230,22 @@ stdout Strikethrough struct subpaths +subschema +Subscribable +subscribable +SVGs svg tcp tls tmp toc todo +transpilation tsx TTL typeof ui +uncached undefined uri ux @@ -247,4 +265,4 @@ yml # ============================================================================= cn ko -ru \ No newline at end of file +ru From 2b605432688d324bdbb39b2a2ca75a905c2d3877 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:26:05 -0700 Subject: [PATCH 12/13] regexify vocab list --- .../config/vocabularies/Mintlify/accept.txt | 50 ++++++------------- 1 file changed, 16 insertions(+), 34 deletions(-) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index d9e20502c..8de2f7e81 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -8,27 +8,20 @@ bearerAuth borderRadius camelCase discoverability -callout -Callouts -callouts +(?i)callouts? drilldown expandables favicon isHidden -Mintlify -mintlify -modeToggle -ModeToggle +(?i)mintlify +(?i)modetoggle myName myObject onboarding -openapi -OpenAPI +(?i)openapi repo topbar -tooltip -Tooltip -tooltips +(?i)tooltips? url # ============================================================================= @@ -37,13 +30,10 @@ url Angular AWS Azure -Babel -babel +(?i)babel Bitbucket -chatgpt -ChatGPT -Claude -claude +(?i)chatgpt +(?i)claude CloudFront Chromium CircleCI @@ -54,14 +44,12 @@ Django DynamoDB Elasticsearch Entra -ESLint -eslint +(?i)eslint Express Firefox Flask GCP -Git -git +(?i)git GitHub GitLab Go @@ -72,8 +60,7 @@ Hightouch IntelliJ Java JavaScript -Jest -jest +(?i)jest JSDoc Kotlin Kubernetes @@ -82,8 +69,7 @@ Linux LLMs Lucide macOS -mcp -MCP +(?i)mcp MDX Mixpanel Mocha @@ -102,8 +88,7 @@ PNPM Posthog Postman PostgreSQL -Prettier -prettier +(?i)prettier Python React Redis @@ -119,10 +104,8 @@ Terraform TypeDoc TypeScript Unix -Vercel -vercel -Vite -vite +(?i)vercel +(?i)vite Visual Studio Code VS Code vscode @@ -130,8 +113,7 @@ Vue Vuex Webflow WebKit -Webpack -webpack +(?i)webpack WebStorm Zapier From 036e3c5720cff5691051a08f3fae4e93c7c1d069 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 19 Sep 2025 17:27:10 -0700 Subject: [PATCH 13/13] grammar --- .vale/styles/Google/Quotes.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale/styles/Google/Quotes.yml b/.vale/styles/Google/Quotes.yml index d7161c5c7..d8eb51fd3 100644 --- a/.vale/styles/Google/Quotes.yml +++ b/.vale/styles/Google/Quotes.yml @@ -4,5 +4,5 @@ link: 'https://developers.google.com/style/quotation-marks' level: error nonword: true tokens: - # Match quotes with trailing punctuation, but exclude like JSON + # Match quotes with trailing punctuation, but exclude content in JSON - '(?