Fix Vale style warnings from PRs merged in the last week

[mintlify]

Summary

Audited Vale spellcheck CI warnings across PRs merged to mintlify/docs between 2026-04-30 and 2026-05-06 (38 PRs with Vale findings). Deduplicated warnings per file and applied style-only fixes that preserve content meaning.

Most fixes are conservative rewrites of passive voice into active voice and corrections to terminology (json → JSON, markdown → Markdown, Endpoint → Endpoints, above → preceding/before).

Files updated (35)

• agent/slack.mdx — passive voice
• ai/mintlify-mcp.mdx — Endpoint → Endpoints
• ai/model-context-protocol.mdx — above → at or above (rephrased)
• api/agent/v2/{create-agent-job,get-agent-job,send-message}.mdx — passive voice
• api/analytics/assistant-caller-stats.mdx, api/preview/trigger.mdx — passive voice
• assistant/index.mdx — passive voice
• cli/commands.mdx — passive voice
• components/{frames,icons,tiles,view,visibility}.mdx — markdown → Markdown, above → before, clicked/selected rephrased
• create/files.mdx — Stylesheets → Stylesheet
• customize/custom-domain.mdx — passive voice (PR docs: remove Vercel reference from custom domain TLS provisioning #5687)
• deploy/{cloudflare,deployments,github,vercel}.mdx — passive voice and GitHub App heading capitalization
• editor/{branching-and-publishing,configurations,git-essentials,pages,share-a-preview,tutorial}.mdx — passive voice, will, ellipses, above
• guides/{improving-docs,maintenance,navigation,seo,style-and-tone}.mdx — passive voice, will, ellipses
• integrations/analytics/posthog.mdx — passive voice
• optimize/feedback.mdx — passive voice (PR Clarify detailed feedback filter behavior #5669)
• workflows/manage.mdx — passive voice

Warnings intentionally not fixed (false positives or convention conflicts)

These items were flagged by CI but left as-is because changing them would change meaning, contradict established Mintlify conventions, or fix a false positive:

• Filenames flagged as terminology — docs.json, vercel.json, posthog.openapi.json, admin-openapi.json, analytics.openapi.json, llms.txt, skill.md were repeatedly flagged by Use 'JSON' instead of 'json' and similar rules. These are literal filenames; lowercasing the extension is correct.
• Em-dashes with surrounding spaces (—) — Don't put a space before or after a dash conflicts with the established style across the docs (organize/navigation.mdx, editor/navigation.mdx, workflows/index.mdx, editor/share-a-preview.mdx, etc.). Recommend a Vale exception or a docs-wide style decision before mass-editing.
• Page titles flagged as needing lowercase — Callouts, Expandables, Endpoints (page heading), Monorepo setup, Subscribable changelogs, Setup heading in osano.mdx. Page titles and section headings legitimately start with capitals; the WordList rule conflicts with Headings rule.
• Plural section headings — ## Dropdowns, ## Breadcrumbs in organize/navigation.mdx. Vale wants singular per WordList, but plural is correct for these section concepts.
• Product / proper-noun spelling — Cursor rule fires on the noun "cursor" (text cursor) in editor/branching-and-publishing.mdx, editor/collaborate.mdx, editor/pages.mdx, editor/keyboard-shortcuts.mdx. The text cursor sense is correct; flagging is a false positive.
• Real words flagged as misspellings — CRMs, minimap, autosaves, autosave, Sunsetting, reshare, legacy_token, informat (substring of information), cdnjs, templated, dismissibility. All real words/identifiers; not changed.
• TXT DNS record name — Use 'txt' instead of 'TXT' and Spell out 'TXT' in customize/custom-domain.mdx. TXT is the canonical DNS record type and should remain capitalized.
• Example / quoted UI labels — "NEW", "BETA" badge example text in editor/navigation.mdx; user-question examples ("How do I set up authentication?") in agent/slack.mdx. These are literal examples and should not be edited.
• changelog.mdx — Vale CI emits ~130 warnings on changelog.mdx, but .vale.ini explicitly excludes this file ([changelog.mdx] BasedOnStyles = ""). This appears to be a CI-side bug rather than legitimate findings, so no edits were applied.
• JSX/code blocks in index.mdx and customize/themes.mdx — className, png, semicolon warnings inside export const JSX components. Vale's MDX block ignore rules should cover these; flagging is a false positive.
• API field names in response docs — resolutionStatus, queryCategory in api/analytics/assistant-conversations.mdx, **api** in api/analytics/assistant-caller-stats.mdx. These are literal API field names.
• Pedagogical passive voice examples — In guides/style-and-tone.mdx, several passive constructions are flagged but appear inside example blocks teaching about passive voice. Restructuring would lose the teaching point.

Validation

• mint broken-links: passes (no broken links).
• mint validate: fails the same way before and after this change because docs.json has a pre-existing schema error in redirects that is unrelated to this PR.

---

Note

Low Risk
Low risk because changes are prose-only edits (terminology, capitalization, and active voice rewrites) with no behavior, API contract, or configuration changes.

Overview
Style-only documentation cleanup to address Vale CI warnings across many pages.

Rephrases sentences to active voice and clarifies wording in agent/API/editor/deploy/guide docs, plus standardizes terminology/capitalization (for example markdown→Markdown, Endpoint→Endpoints, GitHub App→GitHub app) and a handful of minor phrasing tweaks (e.g., “above”→“before/preceding”).

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mintlify	🟢 Ready	View Preview	May 7, 2026, 3:35 PM