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

mintlify · 2026-06-04T15:24:47Z

Summary

Audited Vale spellcheck warnings on the head SHAs of every PR merged into mintlify/docs between 2026-05-28 and 2026-06-04 (the Mintlify Validation (mintlify) - vale-spellcheck CI check). Deduplicated by (file, line, rule) and applied accurate, style-only fixes to English MDX files.

Changes

agent/slack.mdx: replaced a [Semicolons]-flagged semicolon with a period in the Slack agent install callout.
workflows/manage.mdx: removed spaces around em-dashes in the trigger list ([EmDash]), and made "Runs when content is pushed" active ("Runs whenever you push content") ([Passive]).
workflows/index.mdx: removed spaces around em-dashes in the trigger list ([EmDash]).
workflows/reference.mdx: made "If any changes are needed for the maintenance workflow" active ([Passive]).
guides/use-workflows.mdx: removed spaces around em-dashes in the "Repetitive / Time-consuming / Reactive" list ([EmDash]).
guides/linking.mdx: made "how your documentation is organized" active ("how you organize your documentation") ([Passive]).
organize/settings-reference.mdx: removed spaces around em-dash in the directory listings type union ([EmDash]).
organize/settings-structure.mdx: replaced a [Semicolons]-flagged semicolon with a period in the directoryListing description.

Context

Vale config: .vale.ini already excludes changelog.mdx and all locale directories (es/, fr/, zh/) via BasedOnStyles = "", so warnings reported on those files are stale or out-of-scope and were not acted on.
Scope: 40 PRs merged in the window. For each PR, I pulled the vale-spellcheck check run on the PR head SHA, parsed output.text, and deduplicated findings by (file, line, rule). Several PRs had no vale-spellcheck check on their head SHA (likely run before the check was wired up); those were skipped. PRs with Found 0 suggested changes were also skipped.
Validation: mint validate reports only the pre-existing docs.json contextual.options[1] = "download-spec" enum warning (unchanged by this PR). mint broken-links passes.

Findings not changed (flagged for human review)

Warnings I deliberately did not auto-fix, with reasons:

File:line	Rule	Why not fixed
`api-playground/openapi-setup.mdx:164:157`	`[Passive]` "is hidden"	Phrase reads "The option is hidden for deployments behind `auth` or `userAuth`"; rewriting to active voice changes which actor performs the hiding and risks misleading readers.
`api-playground/openapi-setup.mdx:276:133`	`[Spelling]` "Pre"	"Pre pills" is intentional jargon paired with "Post pills" in the same paragraph; should be added to the Vale vocabulary rather than rewritten.
`customize/fonts.mdx:3:68`	`[Headings]` "Google Fonts"	"Google Fonts" is a proper product name; prefer adding to `.vale/styles/config/vocabularies/Mintlify/accept.txt` over changing capitalization.
`guides/linking.mdx:218:1`	`[OxfordComma]` "bookmarked and shared links"	Two-item adjective list; Oxford comma does not apply. False positive.
`workflows/manage.mdx:60:114`	`[Passive]` "be installed"	The text was already rewritten in PR #6032 to imperative ("install the Mintlify GitHub App"); the warning is stale and no longer matches the current file.
`workflows/reference.mdx:17:262`	`[Spelling]` "unmerged"	Standard Git terminology; should be added to the Vale vocabulary.
`agent/slack.mdx:72:10`	`[FirstPerson]` " I "	The "I" appears inside an example user prompt ("How do I set up authentication?"); rewriting it would change the example.
`ai/mintlify-mcp.mdx:24:5`	`[OptionalPlurals]` "Endpoints"	Title-case column header in a comparison table; rewriting to lowercase would break visual parallelism with adjacent headers.
`ai/mintlify-mcp.mdx:114:272`	`[Passive]` "are paginated"	"Results are paginated through an opaque `cursor`" describes API behavior precisely; an active rewrite ("Use `cursor` to paginate results") subtly changes the meaning.
`ai/mintlify-mcp.mdx:138:51`	`[Spelling]` "legacy_token"	Code identifier inside an example prompt; false positive.
`ai/mintlify-mcp.mdx:139:128`	`[WordList]` "rest"	"the rest of the section" — "rest" means "remainder" here, not the REST acronym. False positive.
`organize/settings-reference.mdx:2:14`, `3:49`, `organize/settings-structure.mdx:3:145`, etc.	`[WordList]` "json → JSON"	The matches are inside literal filenames (`docs.json`); the substitution rule does not understand filenames. False positives.
`organize/settings-reference.mdx:157:1`, `163:1`, `209:1`, `215:1`, `organize/settings-structure.mdx:185:3`	`[Spelling]` "Sidebar" / "Dropdown"	Sentence-initial capitalization is grammatically required; the Vale vocabulary only lists lowercase forms. Vocabulary update needed, not a content change.
`changelog.mdx` (≈130 warnings reported by `vale-spellcheck` on PR #6068's repo-wide scan)	various	`.vale.ini` excludes `changelog.mdx` from all styles. Warnings are stale; the file is intentionally not linted.
All warnings in `es/`, `fr/`, `zh/` files	various	Locale directories are excluded from Vale styles and are out of scope per the workflow brief (English files only).

Note

Low Risk
Documentation-only wording and punctuation changes with no runtime, API, or configuration behavior impact.

Overview
This PR applies Vale style fixes across English and localized MDX (es/, fr/, zh/) so copy matches lint rules for em dashes, semicolons, and passive voice.

English docs get the substantive edits described in the PR: split a semicolon into two sentences in the Slack agent install note; tighten workflow trigger bullets (no spaces around em dashes; content update wording is more direct in workflows/manage.mdx); switch workflow “when to use” lists to the same dash style (and colons in the English use-workflows page); rephrase maintenance-workflow and linking guidance into active voice; and normalize navigation.directory type lines (em dash spacing, semicolon → period in settings structure).

Locale files mirror the same punctuation and phrasing patterns in Slack, linking, workflows, and docs.json navigation reference pages—wording stays translated, but list formatting and sentence breaks align with the English fixes.

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

mintlify · 2026-06-04T15:31:02Z