Documentation quality check: fix gaps in recently changed pages

[mintlify]

Summary

Evaluated the 34 English MDX pages changed in the last day (editor overhaul, new CLI MDX extension page, POC onboarding, llms.txt/MCP updates), fixed the five with the highest-cost gaps, and mirrored every fix into the Spanish, French, and Chinese translations. All corrected facts were verified against the mintlify/server and mintlify/mint codebases.

Changes

poc-onboarding.mdx (+ es/, fr/, zh/)

• Gap: Claimed authentication requires a custom domain or *.mintlify.app subdomain. Authentication works on .mintlify.site subdomains (verified in clientAuth.controller.ts and consistent with /deploy/authentication-setup). This could push evaluators into unnecessary DNS work.
• Gap: Step 4 described a stale editor UI (Live site dropdown → Branches tab, eye/</> icons) that contradicts the overhauled editor docs.
• Fix: Corrected the auth-domain claim and rewrote Step 4 (branch creation, mode switching, preview deployments, publish flow) to match /editor/publish and /editor/review.

editor/index.mdx (+ es/, fr/, zh/)

• Gap: Said publishing from a feature branch can update the live site immediately. Contradicts /editor/publish and the publish action logic in the dashboard code (feature branches offer Save in branch / Create pull request).
• Fix: Reworded to state that feature-branch changes only go live after merging into the deployment branch.

deploy/deployments.mdx (+ es/, fr/, zh/)

• Gap: Framed the Mintlify GitHub App as a universal prerequisite, misleading GitLab and Bitbucket users.
• Fix: Qualified the prerequisite as GitHub-specific and linked /deploy/gitlab and /deploy/bitbucket. Also replaced pre-existing HTML entities with real apostrophes in the French file.

cli/commands.mdx (+ es/, fr/, zh/)

• Gap: The mint config keys table listed only subdomain (used by mint automations), while the same page references dateFrom/dateTo defaults for mint analytics. Self-contradicting reference.
• Fix: Added dateFrom and dateTo rows and expanded subdomain usage to mint dev, mint analytics, mint add-domain, and mint score (verified in packages/cli/src/config.ts and command sources).

editor/pages.mdx (+ es/, fr/, zh/)

• Gap: The Private pages section started mid-story without defining private pages or how to create one, and referenced a Private section when the UI label is Personal (verified in private-pages-section.tsx).
• Fix: Added a definition and creation steps, and corrected the section name to Personal.
• SEO: Lengthened the frontmatter description from 118 to 135 characters to cover the page's full scope (version restore, private pages).

Best-practices pass

• Translations: All five English changes mirrored into es/, fr/, and zh/ counterparts, preserving markup, <div id> anchor wrappers, language-prefixed internal links, and each file's existing terminology conventions. No docs.json navigation or redirect changes were needed.
• Broken links: mint broken-links passes; no broken links introduced.
• SEO: Audited titles and descriptions of all changed pages; only editor/pages.mdx needed a fix (short description, updated in all four languages).
• Grammar/style: No typos, broken markdown, or style-guide violations found in the changed files.

Also worth reviewing (not touched)

• editor/settings.mdx — Appearance settings (Show all files, Open live preview in new tab, draft-PR default) are undocumented despite inbound links from editor/pages.mdx, editor/review.mdx, and the changelog.
• editor/publish.mdx — no role prerequisite for publishing; "Auto publish" vs settings page's "Main branch autocommits" naming drift; table omits Merge and publish for Mintlify-hosted feature branches.
• editor/agent.mdx — roles and usage limits for the agent unstated (limits unverifiable from repos).
• deploy/reverse-proxy.mdx — routing table omits /.well-known/mcp/*, /.well-known/agent-card.json, and /.well-known/api-catalog paths advertised by ai/llmstxt.mdx.
• ai/mintlify-mcp.mdx — dashboard location of the Publishing toggle not given (exact URL unverifiable).
• changelog.mdx — /editor/drafts link resolves only via redirect to a page that never mentions drafts.

Open gaps left unfixed (unverifiable)

• Whether a custom llms.txt suppresses the generated /_llms/ split indexes.
• Editor smart-substitution opt-out, suggestion Git persistence, and agent publish capability. These need product confirmation before documenting.

---

Note

Low Risk
Documentation-only corrections and translation parity; no runtime, auth, or deployment behavior changes in this repo.

Overview
Documentation accuracy pass across English and mirrored es/, fr/, and zh/ pages—no product code changes.

CLI (mint config): The configuration-keys table now lists dateFrom and dateTo for mint analytics, and documents which commands use subdomain (not only mint automations).

Deployments: Auto-deploy setup is described as GitHub-specific (with links to GitLab/Bitbucket), and troubleshooting no longer assumes every customer uses the GitHub App.

Editor: Publishing from a feature branch is clarified—live site updates only after merge to the deployment branch. Private pages docs add what they are, how to create them in the Personal section (replacing the old Private label), and expanded page metadata.

POC onboarding: Step 4 is rewritten for the current editor (toolbar branch creation, keyboard shortcut for visual/MDX, Create pull request preview deployments, merge-to-publish). Spanish, French, and Chinese copies also correct authentication guidance (.mintlify.site vs custom subpath) and link to authentication setup.

French deploy/deployments.mdx replaces HTML-escaped apostrophes with normal characters.

^{Reviewed by Cursor Bugbot for commit d8d7deb. 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	Aug 26, 2026, 10:19 AM

[mintlify]

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

Project	Status	Preview	Updated (UTC)
tomee	🟡 Building	–	Aug 26, 2026, 10:17 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.