Documentation quality check: editor tutorial + invalid MDX fix

[mintlify]

Summary

Reviewed 14 English MDX pages changed since the last run and filled the two highest-cost reader gaps: missing prerequisites in the editor tutorial and missing "how to locate the broken page" guidance in the invalid-MDX help-center article.

Changes

editor/tutorial.mdx (tutorial)

Identified gaps:

• No prerequisites, so a first-run user landing on the page has no path to open the editor or check whether their role can publish.
• No pointer for discarding a branch when the user decides not to publish.

Added:

• A Prerequisites info callout linking to /editor for access and to /dashboard/roles for the admin/editor role requirement, noting that viewers can edit and comment but not publish or request review.
• A one-liner at the end of Step 1 pointing to /guides/branches#delete-a-branch for discarding a branch.

help-center/publish-button-disabled-invalid-mdx.mdx (how-to)

Identified gaps:

• The page said the tooltip reports a count of broken pages but never told the reader how to find which page has the error.
• The page listed invalid frontmatter YAML as a cause but gave no remediation guidance or reference.
• The agent section didn't mention the agent's scope, so readers with multiple broken pages didn't know how to fix them all.

Added:

• A "Find the affected page" section describing how to open the publish menu, walk each changed file, and use source mode to spot the parsing error.
• A frontmatter-specific tip covering quoting, indentation, and closing quotes, with a link to /organize/pages#page-metadata.
• A note in the agent section that the agent uses the open page as initial context by default and can be asked to find and repair every broken page across the branch, with a link to /editor/agent.

Also worth reviewing

These pages had smaller, mostly low-severity gaps that didn't warrant edits this run:

• editor/agent.mdx — plan availability and data-handling notes for the agent aren't stated. Left unfixed: pricing/plan and privacy details aren't verifiable from the docs or reference repos.
• editor/collaborate.mdx — no explicit resolve/reopen flow for comment threads, no stated concurrent-editor limit, no comment-panel filtering/navigation docs.
• editor/index.mdx — merge conflicts are mentioned as "flagged" but the resolution UX isn't explained or linked.
• editor/keyboard-shortcuts.mdx — "suggesting mode" is used without a gloss; no note on whether shortcuts are customizable.
• editor/pages.mdx — no stated size limit for non-media uploads in the Files section.
• editor/publish.mdx — no troubleshooting section for publish failures, no in-page rollback guidance.
• editor/review.mdx — no explicit fallback (use preview deployments) for sites with unsupported live-preview auth types.
• editor/settings.mdx — PR-instructions scope (per-user vs. deployment) isn't stated; behavior at the 20,000-character limit isn't described.
• guides/branches.mdx — no in-page guidance for recovering a deleted branch or resolving merge conflicts.
• poc-onboarding.mdx — pricing/scope and post-POC next steps aren't covered.
• cli/commands.mdx — exit codes aren't consistently documented per command; runtime prerequisites (Node/OS) aren't listed on the page.
• automations/create.mdx — no gaps identified.

---

Note

Low Risk
Documentation-only MDX edits with no application or security impact.

Overview
This PR fills documentation gaps in the editor tutorial and the invalid MDX help article, with matching updates in es, fr, and zh.

The editor tutorial now opens with an Info callout on who can publish (admin/editor vs viewer) and links to roles; localized tutorials also list editor access and a link to the web editor overview. Step 1 adds how to discard a branch via Delete branch and points to the branches guide.

The invalid-MDX help page adds a Find the affected page section (use the publish menu’s changed-file list and source mode), frontmatter YAML fix tips with a link to page metadata, and clearer agent guidance (defaults to the open page; can repair all broken pages on the branch). Some locale files normalize agent section headings to ##.

^{Reviewed by Cursor Bugbot for commit 0e21320. 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
mintlify	🟢 Ready	View Preview	Sep 23, 2026, 6:01 PM