Documentation quality check: fix gaps in recently updated pages

[mintlify]

Summary

Evaluated the 60+ English MDX pages changed since 2026-08-25 against reader questions per Diataxis category, fixed the five pages with real gaps, then mirrored the changes into es, fr, and zh and applied an SEO fix.

Changes

components/mdx.mdx

• Gap (high): The Note claimed headings inside <MDX> do not appear in the page's table of contents. This is wrong: the implementation merges fragment headings into the page TOC in document order (mint commit f9dbf617, remarkMdxExpandExpressions.ts).
• Fix: Corrected the Note to state that headings are merged into the TOC, including headings in branches that never render.

editor/settings.mdx

• Gap (medium): The intro lists Appearance as a settings category, and editor/pages.mdx and editor/review.mdx link here for specific Appearance toggles, but no Appearance section existed.
• Fix: Added an Appearance section documenting all four toggles (fit to full width, breadcrumbs, live preview in new tab, show all files), verified against editor-settings-form.tsx in the dashboard code.

create/list-table.mdx

• Gap (medium): The frontmatter description promises task list checkboxes, but the page had no task list section.
• Fix: Added a "Task list" section with - [ ] / - [x] syntax (supported via remark-gfm).

ai/bring-your-own-model.mdx and credits.mdx

• Gap (low): Both pages said "reduced credit rate" without quantifying it.
• Fix: Stated the rate is half the standard rate, verified against BYOK_TOKENS_PER_CREDIT_MULTIPLIER = 2 in server/api/utils/billing/mintlifyCredits.ts.

reference/glossary.mdx

• Gap (low): The description promises "API playground" terminology, but no entry defined it.
• Fix: Added an "API playground" entry linking to /api-playground/overview.

Maintenance pass

• Translations: Mirrored all six English changes into es/, fr/, and zh/ counterparts, following repo conventions (English-slug <div id> heading wrappers, language-prefixed internal links, UI labels kept in English).
• SEO: Expanded the ai/bring-your-own-model.mdx description from 100 to 139 characters to cover automations and the Enterprise plan requirement; mirrored in all three languages.
• Broken links / validation: mint validate and mint broken-links pass.
• Typos / style: Nothing to flag in the touched files.

Gaps left unfixed

• editor/pages.mdx: how to delete or move a page is not documented. The editor UI behavior isn't verifiable from the available code, so writing it would risk inventing UI steps.
• ai/bring-your-own-model.mdx: the exact per-product fallback to Mintlify's models for Anthropic and OpenAI-compatible providers is only partially traceable in server code, so the "some AI products" wording was left as is.

---

Note

Low Risk
Documentation-only edits with no application code, auth, or data-handling changes.

Overview
Corrects several English docs that were wrong or incomplete, then mirrors the same updates into es, fr, and zh.

<MDX> table of contents: The Note now states that headings inside <MDX> do appear in the page TOC (including headings on never-rendered conditional branches), replacing the previous incorrect claim that they are excluded.

Editor settings: Adds a dedicated Appearance section with the four personal toggles (full width, breadcrumbs, preview in new tab, show all files), including the 768px default width and keyboard shortcut for showing all files.

Lists: Adds a Task list section to the list/table guide with - [ ] / - [x] syntax and examples.

Glossary: Adds an API playground entry (OpenAPI-generated interactive requests) in English and localized glossaries.

BYOK / credits: Expands BYOK page meta descriptions to mention automations and Enterprise (SEO). Localized credits and BYOK credit sections now say usage is billed at half the standard credit rate instead of a vague “reduced rate.”

^{Reviewed by Cursor Bugbot for commit 4769f55. 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 29, 2026, 2:24 PM

[mintlify]

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

Project	Status	Preview	Updated (UTC)
tomee	🟡 Building	–	Aug 29, 2026, 2:22 PM

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