docs: fix Vale warnings from PRs merged in the last week by mintlify[bot] · Pull Request #6222 · mintlify/docs

mintlify · 2026-06-18T15:22:02Z

Summary

Style-only fixes for Vale warnings introduced by the 45 PRs merged to main since 2026-06-11 (base 5a3d1dd… → head 2ccd573…). 29 of 92 warnings are addressed here; the remainder are documented below as false positives that need human judgment.

Changes

Fixed across 13 English .mdx files (no es/, fr/, zh/, or changelog.mdx):

advanced-support.mdx — Removed spaces around en-dash separators in priority labels (P0 – Critical → P0–Critical); replaced functionality → capability/feature; rewrote 4 passive constructions to active voice.
agent/integrations.mdx — Rewrote are shared passive.
ai/contextual-menu.mdx — Rewrote to be installed → installing.
api/analytics/assistant-conversations.mdx — Rewrote was captured passive in pageUrl description.
create/changelogs.mdx — Rewrote are hidden passive in tag-filter description.
credits.mdx — Rewrote 4 passive constructions (are billed, are charged, are disabled, are prorated).
editor/branching-and-publishing.mdx — ready to be merged → ready to merge; replaced semicolon with period.
editor/configurations.mdx — Rewrote is organized and is shown passives.
editor/pages.mdx — are unlisted → remain unlisted.
editor/tutorial.mdx — Rewrote is approved and merged passive.
guides/assistant-embed.mdx — ## What you will build → ## What you'll build.
optimize/seo.mdx — Rewrote are served passive; collapsed double-space.
organize/hidden-pages.mdx — is hidden ... is visible → stays hidden ... remains visible.

Context

Triggered by the weekly Vale audit workflow (.mintlify/workflows/vale-audit.md). Vale was run locally because the CI workflow file for Vale isn't on main.

Warnings left for human review

These warnings remain in Vale's output but appear to be false positives or would change meaning if "fixed." Listing them here so a writer can confirm rather than guessing:

Vale.Terms — sentence-case headings, UI labels, code, and filenames

Vale's Terms rule prefers lowercase/plural forms (e.g. endpoints?, sidebars?, subscribable) for many words, but these patterns are typically intentional:

Sentence-case headings where the term is the first word: ## Endpoints (api/introduction.mdx L10), ### Diff view (editor/pages.mdx L57), ### Subscribable changelogs (create/changelogs.mdx L104), ## Verification TXT records (customize/custom-domain.mdx L56), ### Content-Signal directives (optimize/seo.mdx L342).
Bold list-item labels that mirror UI: - **Dismissible**:, - **Drilldown**:, - **Metatags**: (editor/configurations.mdx L84/L122/L179); - **Rebase**: (editor/settings.mdx L94); - **Emoji picker** (editor/keyboard-shortcuts.mdx L62); - **Sidebar titles** (organize/pages.mdx L17); - **Sidebar title** (editor/pages.mdx L104).
Sentence-start prose: Sidebar anchor links. / Dropdown menus. (organize/settings-reference.mdx L157/L163/L209/L215).
Filenames flagged as case errors for json / svg / png extensions: docs.json in frontmatter and prose (organize/settings-reference.mdx L2, organize/settings-appearance.mdx L3, editor/agent.mdx L60, api/analytics/assistant-conversations.mdx L3); /logo/light.svg, /favicon.svg in JSON (organize/settings-appearance.mdx L85); dashboard.png in tree diagrams (guides/internationalization.mdx L665/L667/L669).
Multi-cursor / generic editor cursor flagged as the Cursor IDE term: editor/branching-and-publishing.mdx L155/L161; editor/keyboard-shortcuts.mdx L103/L104/L105 (Add cursor, Add cursor above, Add cursor below are command labels); editor/pages.mdx L51/L116.
agents as a common noun (the rule expects the AGENTS.md filename): ai/model-context-protocol.mdx L17/L29/L34/L39/L43/L85 (about Claude/Cursor/Windsurf agents); optimize/seo.mdx L344/L364 (about AI user agents).

Vale.Spelling — code identifiers

Field names inside backticks/code fences: resolutionStatus, queryCategory, pageUrl (api/analytics/assistant-conversations.mdx L24–L26); handleSubmit (guides/assistant-embed.mdx L183, inside a JSX code block).

Mintlify.Semicolons — semicolons inside JSX/code blocks

guides/assistant-embed.mdx L76/L127/L128/L132 are inside fenced JSX/JS code, not prose.

Mintlify.Headings — acronyms and proper nouns in headings

Verification TXT records (customize/custom-domain.mdx L56), Subscribable changelogs (create/changelogs.mdx L104), Content-Signal directives (optimize/seo.mdx L342) are valid sentence case; the rule misfires on the embedded acronym/proper noun.

Mintlify.Acronyms

TXT in Verification TXT records heading (customize/custom-domain.mdx L56) is the standard DNS record type and is widely understood.
NOT in **noindex: true→ does NOT applyhidden** (organize/hidden-pages.mdx L153) is intentional emphasis in a comparison row.

Mintlify.FirstPerson

editor/agent.mdx L13/L15 — the rule matches the letter I inside <kbd>Cmd</kbd> + <kbd>I</kbd> keyboard-shortcut markup, not first-person prose.

Mintlify.Will

advanced-support.mdx L64 — Mintlify will use commercially reasonable efforts to meet the following service levels: is intentionally contractual SLA wording. Recommend leaving as-is.

Mintlify.Passive (left for review)

advanced-support.mdx L103 as features are scoped — fits the parallel list structure (see status … and provide feedback as features are scoped); rewording disrupts the bullet flow.
ai/model-context-protocol.mdx L171 are read-only — the rule misparses the compound adjective read-only as a passive verb.

Mintlify.WordList (left for review)

advanced-support.mdx L14 Email — starts a table cell (| Email or dashboard | …), so the capital is sentence-case style.
editor/keyboard-shortcuts.mdx L104 above — refers to the editor command Add cursor above, which is a literal UI label; "preceding" would misname the command.

Mintlify.Quotes

organize/settings-appearance.mdx L379 "/favicon.svg", — the rule wants the comma inside the quotes, but the content is JSON, where the comma must be outside the string literal.

Mintlify.EmDash (already fixed but worth flagging)

advanced-support.mdx L68–L71 used P0 – Critical (en-dash with spaces) in a priority table. I removed the spaces (P0–Critical) to match the rule and align with the P0–P3 form already used elsewhere in the file. If the spaced form is the intended house style, revert these four lines.

Note

Low Risk
Documentation-only prose and punctuation updates with no code, auth, or deployment logic changes.

Overview
This PR applies style-only documentation edits to clear Vale warnings introduced by recent merges. Changes are limited to wording and punctuation in .mdx files; there is no product or API behavior change.

English docs get passive-voice rewrites, clearer active phrasing, and small terminology tweaks (for example functionality → capability / feature in advanced support, Overages are charged → cost wording in credits, and pageUrl described as unavailable when no path exists). Advanced support priority labels use tight en-dashes (P0–Critical instead of spaced P0 – Critical), and several SLA/FAQ sentences name Mintlify engineering as the actor instead of passive constructions.

The same patterns are mirrored in es/, fr/, and zh/ for the touched pages (support tiers, agent integrations, contextual menu, analytics, changelogs, credits, editor publishing/config/tutorial, SEO robots.txt copy, hidden pages). guides/assistant-embed.mdx renames the section heading to What you'll build.

Remaining Vale hits called out in the PR (terms in UI labels, code identifiers, contractual will, etc.) are intentionally left for human review as likely false positives.

^{Reviewed by Cursor Bugbot for commit 19b6d4e. Bugbot is set up for automated code reviews on this repo. Configure here.}

mintlify-development · 2026-06-18T15:22:07Z