* docs: document OpenAPI overlay support
* docs: translate OpenAPI overlay docs to fr, es, zh and trim zh description
* docs: describe overlay failure behavior on hosted deployments
* docs: tighten overlay section and merge in wording from #7261
Consolidates the two overlay docs PRs into this one. Keeps this PR's
structure and anchors (already referenced from the glossary, settings pages,
and translations), tightens the prose toward the page's voice, leads with
"Use OpenAPI Overlays to...", drops repeated "Mintlify" subjects, and renames
the example heading to "Rename a path" to match the page's imperative
headings. fr/es/zh mirrors updated to match.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: brandonmcconnell <brandon@mintlify.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
* Correct hidden, noindex, and llms.txt docs against implementation
- Add an llms.txt column to the hidden pages comparison table and split the
frontmatter vs. navigation-removal rows, which differ for the noindex tag
- Replace the "hidden: false is undefined behavior" claim with actual behavior
- llms.txt lists pages in navigation order, not repository order
- Descriptions come from the first paragraph, truncated at 300 characters; the
spec-info claim applies to llms-full.txt, not llms.txt
- Document the Optional section and the full Link header rel values
- Note the default language/version scope and that the 100k cap is llms.txt only
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Correct what "Don't index project" does to search indexes
Enabling deployment-level noindex removes the site from Mintlify Index
(the universal search collection) via skipSite. It does not clear the
deployment's own Chroma collection, and no search, assistant, or MCP
query path checks deployment.noindex.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* document lastUpdatedDate precedence for last modified timestamp
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* rename lastUpdatedDate to lastUpdated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* revert to lastUpdatedDate
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs: document auto-route to preferred language for multilingual docs
* docs: translate auto-route to preferred language section
* docs: trim auto-route to preferred language section
Cut the section down to what a user needs to turn the setting on:
what it does, the Add-ons page link, and the two behaviors that
affect them (root-only redirects, switcher choice wins).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* 💅
---------
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: standardize documentation writing style
* docs: apply brand tone and style fixes
* docs: refine brand tone and writing style
* Revert changelog.mdx changes
The changelog is generated content and shouldn't be rewritten by the
brand tone and writing style pass.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Update ai/model-context-protocol.mdx
* Update ai/model-context-protocol.mdx
---------
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: document assistant page mode
Adds an Assistant subsection under Page mode in organize/pages.mdx for
the new mode: "assistant" frontmatter option (mintlify/mint#9451),
which renders a page as a full-screen AI assistant experience.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* 💅
---------
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document markdown.instructions for custom agent instructions
Add a "Custom agent instructions" section to the Markdown export page
covering the markdown.instructions docs.json setting (string or array),
the rendered Agent Instructions block, and where it appears. Cross-link
it from the llms.txt structure list.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* 💅
* docs: add markdown block to docs.json schema reference
Document the previously-undocumented markdown config block in the
schema reference, covering markdown.schema and the new
markdown.instructions setting, in both the quick reference table and
the full property reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix: reduce Vale false positives via vocab and config updates
- Make English-word vocab entries case-insensitive so sentence-start
capitalization and normal prose usage stop flagging (agents, rest,
cursor, setup, endpoints, etc.)
- Add vocab entries for filenames and code identifiers that appear in
frontmatter and JSX contexts (docs.json, llms.txt, CLAUDE.md, etc.)
- Ignore openapi frontmatter lines, filenames, JSX attributes, email
addresses, and internal link targets via TokenIgnores
- Skip inline code scope and indented code fences
- Add Headings exceptions for proper nouns (Claude Code, GitHub
Actions, Route 53, GA4, etc.)
- Disable linting for the all-code vercel-json-generator snippet
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: resolve all Vale warnings and errors across docs
Content fixes:
- Reword sentences using 'will', first person, spaced em dashes,
'e.g.', Latin abbreviations, and hyphenated adverbs
- Sentence-case headings that started with dotted filenames
- Backtick literal API values instead of bolding them
- Move periods inside quotation marks
- Fix Oxford comma rule misfires by restructuring sentences
False-positive suppression:
- Vale toggles around example user questions, keyboard shortcut keys
(Cmd+I), UI labels, and code samples in JSX contexts that Vale
misparses
- Exclude vale toggle comments from the brace Token/BlockIgnores so
in-document commands actually reach Vale (the greedy brace pattern
was also silently swallowing large regions; now lazy)
- Vocab entries for code identifiers (internal_id, handleSubmit, etc.)
- Per-file rule disables for component docs with dotted JSX names and
files where link-target linting ignores in-document toggles
Result: vale --minAlertLevel warning is clean repo-wide; only
suggestion-level items (Passive, Semicolons, Acronyms) remain.
mint broken-links passes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: correct WordList rule instead of degrading prose
- Restore sentence-start "Email" in advanced-support; the rule now
only flags hyphenated e-mail/E-mail forms
- Restore the idiom "above all else"; the above->preceding swap now
exempts "above all"
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: restore deliberate prose flagged by blunt rules
- Restore spatial 'above the navbar' / 'above a page title' in
custom-scripts; the above->preceding swap now exempts 'above
the/a/an'
- Restore the '= ...' in the react-components named-export example
(the ellipsis is inside inline code) with an Ellipses toggle
- Restore SLA phrasing 'will use commercially reasonable efforts'
with a Will toggle
- Restore the quoted developer question in the GEO guide intro with a
FirstPerson toggle, matching the file's other example questions
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: remove WordList swaps that flag legitimate English
- Drop tablet->device and firewalls->firewall rules; both words are
correct in ordinary prose
- Narrow touch->tap to UI-instruction phrasing (touch the/a) so
'keep in touch' and 'touch devices' stop flagging
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: reposition vale toggles to wrap whole blocks
Toggle comments placed between list items split the lists (restarting
ol numbering in deployments) and comments flush against tables risked
breaking GFM table parsing. Wrap entire lists/tables with blank-line
separation instead. Verified rendering with mint dev: single ol with
two items, tables intact, no comments in visible DOM.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor: prune accept.txt to load-bearing entries
Empirically removed 166 vocab entries (575 -> 409) whose removal
causes no Vale flags across all 908 English pages: dictionary words
that never needed listing (agents, setup, endpoints, webhooks, yaml),
lowercase entries the speller already accepts, and filename entries
made redundant by inline vale toggles.
Kept every case-enforcing entry (API, JSON, GitHub, ...) so casing
policy is unchanged, plus entries that double as capitalization
exceptions for headings (mcp, md, auth, cursor, txt).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Update ai/mintlify-mcp.mdx
* Update api/agent/v2/create-agent-job.mdx
* chore: alphabetize Headings exceptions and accept.txt
Case-insensitive sort, ignoring the (?i) prefix; also drops a
duplicate Scala entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: re-apply OxfordComma rewrite lost in branch merge
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: resolve Vale suggestions batch 1 (acronyms, semicolons, passive voice)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: resolve remaining Vale suggestions (passive voice batch 2)
Rewrite ~90 passive constructions to active voice across deploy,
guides, migration-services, and organize docs. Toggle the deliberate
passive examples in the style-and-tone guide ('by zombies' test).
Add axios/lodash vocab entries for a repositioned code example.
vale . is now fully clean: 0 errors, 0 warnings, 0 suggestions.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs(DOC-389): add Codex CLI guide and MCP connection tab
Adds a guide for using OpenAI Codex CLI with Mintlify docs (AGENTS.md
config + MCP connection), adds Codex to the AI tools nav group, and
adds a Codex tab to the MCP server connection example section.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: add Codex to AI tools list in guides index
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update Windsurf → Devin Desktop across guides and contextual menu
windsurf.com permanently redirects to devin.ai/desktop. Updates:
- guides/windsurf.mdx: rebrand to Devin Desktop, update rules path to
.devin/rules/, update docs links, add MCP config with correct format
- ai/contextual-menu.mdx: replace deprecated "windsurf" identifier with
"devin-desktop" in example config, update description and keywords
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: rename guides/windsurf to guides/devin-desktop, add redirect
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: sweep remaining Windsurf → Devin Desktop references in English docs
Updates ai-native.mdx, guides/index.mdx, guides/claude-code.mdx,
organize/settings-structure.mdx, organize/settings-reference.mdx,
and cli/install.mdx. Changelogs and translation files left as-is
(changelogs are historical records; translations auto-update on merge).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: add Codex tab to Use your MCP server section
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Update docs.json
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: fix Vale warnings from PRs merged in the last week
* docs: mirror Vale style fixes into es/fr/zh translations
---------
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
* fix: clarify mintignore broken-links behavior
Splits the confusing single bullet into two explicit statements:
- Ignored files' outgoing links are not scanned by mint broken-links
- Links from other pages pointing to ignored files are flagged as broken
Closes#4792
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* language
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* clarify MCP returns MD
* Fix doc issues surfaced by user feedback
- Fix claude mcp add --header argument order: the flag must come after
the positional <name> and <url> args because --header is variadic and
otherwise consumes everything that follows it, causing the "missing
required argument 'name'" error users reported.
- Add tip to wrap iframes in Frame component to prevent overflow (user
suggestion on image-embeds page).
- Fix broken anchor link in quickstart CLI tab: /cli/install has no
#clone-your-repository section; replaced with inline git clone
instructions and a correct link to /deploy/github.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Document wide-mode behavior for side panel
Wide mode hides the entire side panel (not just the TOC), including
Panel components and OpenAPI request/response examples. This was
undocumented and actively confused a user who couldn't understand why
their OpenAPI example panels disappeared on wide-mode pages.
- Fix the wide mode description in organize/pages.mdx (it previously
said only the TOC was hidden, but ContentSideLayout.tsx returns null
for wide/center/custom modes entirely)
- Add a Note to components/panel.mdx calling out that the side panel
is absent on wide, center, and custom pages
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Resolve user feedback: clarify path formats, load timing, and analytics config
- react-components: add Constraints section (hooks pre-injected, no npm, no default exports)
- posthog: fix default host from app.posthog.com to ph.mintlify.com (confirmed via source)
- plausible: add ParamField descriptions including server field explanation
- create/text: note that internal links require root-relative paths without file extensions
- create/image-embeds: clarify image paths are root-relative, relative paths unsupported
- create/redirects: show redirects as top-level field in full docs.json example
- customize/custom-scripts: note that custom JS runs after page is interactive, applies globally
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* 💅
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
mintlify[bot]