Editor docs overhaul - #7112
Merged
Merged
Conversation
Accuracy fixes, each verified against mintlify/mint or mintlify/server: - pages.mdx: "Editors and managers can restore them" -> "admins". "Manager" is not a Mintlify role. - index.mdx: publishing on a feature branch does not automatically open a pull request; you choose commit-to-branch or PR. Contradicted the branching page's own table. - branching-and-publishing.mdx: preview deployments build when you open a pull request, not on every branch save. Confirmed in gitlabWebhooks (handleMergeRequestOpenEvent) and cruxWebhooks (keyed on reviewId). tutorial.mdx was already correct. - settings.mdx: rewritten against editor-settings-form.tsx. The panel has four sections, not "two layers", and the entire Appearance section was undocumented - including "Open live preview in new tab", which live-preview.mdx already linked readers to. Corrected three setting labels, noted that draft PRs default to on, added the 20,000-character instruction limit. - live-preview.mdx: link now resolves to /editor/settings#appearance. De-bloat: - Split the media section out of pages.mdx (172 lines, 15 subtopics) into editor/media.mdx and added it to the nav. - Trimmed index.mdx from 11 sidebar-duplicating cards to 4. Translation orphans and redirects: - Deleted 7 translated files whose English source was removed in April and June. The translate automation never cleaned them up, and in PR #6062 it wrote into es|fr|zh/editor/media.mdx 34 days after the English source was deleted. - Dropped /editor/media -> /editor/pages so it stops shadowing the recreated page. - Added /{es,fr,zh}/editor/publish, completing an English-only redirect. - Added /editor/collaborate and its language variants. That page was deleted in June with no redirect and has been a live 404 since. mint broken-links clean, mint a11y clean, vale 0/0/0 on changed files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The editor section had grown to 14 pages, about 40% of which described things a user can see on screen. The ratio was 105 field-enumeration bullets to 42 procedural steps. New structure, organized around what is invisible rather than what is on screen: Overview absorbs git-essentials (concepts + the Git mapping table) Tutorial unchanged Edit content absorbs media and navigation Publish branch mechanics, conflicts, git sync, commit signing Review previews, pull requests, approve and merge Collaborate comments + suggestions + real-time editing Editor agent trimmed Settings absorbs configurations as a pointer Keyboard shortcuts unchanged Removed: git-essentials, media, navigation, live-preview, comments, suggestions, configurations, branching-and-publishing. Added: publish, review, collaborate. configurations.mdx was the clearest cut. It was a 193-line field-by-field mirror of the Site configurations panel, which is a third rendering of information already in the docs.json schema and in organize/settings-* (2,694 lines). It is now a short section in settings.mdx covering only what is specific to editing configuration from the editor: real-time sync, the SVG logo constraint, and the redirects interface. Also cut: block actions, the minimap, code block options, right-click menu enumerations, page settings field lists (already delegated to /organize/pages), and most screenshots of self-evident controls. 1,320 to 848 body lines. Field-enumeration bullets 105 to 29. English redirects added for all eight removed pages. Language variants deliberately omitted: es/fr/zh still carry the old structure, so redirecting those paths now would shadow pages that still exist there. The translation automation should mirror this restructure; verify afterward that no orphans remain. Vale vocabulary widened rather than reworded around: autocommit(s|ed|ing)?, autosav(e|es|ed|ing), dotfile(s)?. mint broken-links clean, mint a11y clean, vale 0 errors on editor/. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Verified every documented shortcut against the bindings in mintlify/mint
rather than inferring them. The app-level set is exhaustive:
mod+backslash, mod+i, mod+k, mod+s, mod+shift+period, mod+z, shift+mod+d,
shift+mod+s. Visual-mode bindings come from the Tiptap extensions.
- Cmd/Ctrl+Shift+F ("Switch between Navigation and Files tree") does not
exist. No such binding is registered anywhere in the dashboard. Replaced
with the real binding at that spot in the UI: Cmd/Ctrl+Shift+. toggles
"Show all files".
- Added Heading 5 and Heading 6. Heading.configure sets levels 1-6 and
preserves the parent Mod-Alt-N shortcuts; the table stopped at 4.
- Added Cmd/Ctrl+G for accordion group, bound in Accordions.tsx.
Confirmed correct and unchanged: Cmd+K search, Cmd+I agent, Cmd+Shift+S
mode toggle, Cmd+Shift+D diff, Cmd+\ sidebar, Cmd+Shift+M comment,
Cmd+Shift+E suggesting mode, Cmd+Shift+X strikethrough, Cmd+K link,
Cmd+Enter line break, Cmd+Shift+8 unordered list, and that source mode
runs Monaco.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Auto publish is available to all deployments, so the settings panel shows "Auto publish" rather than "Main branch autocommits". It is not just a rename: when it is on, the editor hides the branch selector and the Publish button entirely (TopBar returns null for both), so there is no pending state and no review step. Documented that behavior in settings.mdx and added a note at the top of publish.mdx, since that page otherwise assumes a publish step exists. The deployment branch lock was deprecated and removed, so it stays out of the docs. It was already dropped from settings.mdx in the restructure. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Three claims traced to code that never mounts. Ethan confirmed the diff shortcut does not work, which exposed the pattern. - Removed Cmd/Ctrl+Shift+D for diff view. It is registered only at SubBar/index.tsx:488, inside EditorSubBar, which is exported and imported by nothing. There is no live diff shortcut; exitDiff exists only as an onClick in EditorModeContextMenu. - Source mode runs CodeMirror, not Monaco. SourceEditor resolves through source-editor/index.tsx to editor-view.tsx, which imports @codemirror/state and @codemirror/view. Monaco is used only by EmbedModal. The shortcut rows themselves were correct: CodeMirror's defaultKeymap and searchKeymap match VS Code for toggle comment, move line, duplicate line, find, and add cursor above/below, all confirmed against @codemirror/commands. - Rewrote the left panel section of pages.mdx. The tabs are Home and Publishing (EditorNavigationSidebarContents.tsx:62), not Navigation and Files. The Navigation/Files switcher lives in the same dead SubBar component. Home renders the workspace file tree including private pages; Publishing renders the site navigation and site settings. Confirmed by the e2e helper openPublishingNavigation, which queries the Publishing tab by role against the running app. Also corrected in that section: the tree hides docs.json, dotfiles, extensionless files, all-caps Markdown, and css/js/jsx/mjs/cjs/pdf unless Show all files is on; "unlisted" was an invented term, replaced with a link to /organize/hidden-pages; and the folder menu item is "New page", confirmed by e2e, not "New file". Added four source-mode bindings that are real and undocumented: Cmd+B and Cmd+I insert Markdown markers, Cmd+Option+Shift+[ and ] fold and unfold all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ethanpalm
marked this pull request as ready for review
August 26, 2026 02:01
- Updated quickstart.mdx Mintlify-Source: dashboard-editor
- Updated quickstart.mdx Mintlify-Source: dashboard-editor
… into editor-docs-overhaul
This reverts commit 8d1b50c.
- Updated quickstart.mdx Mintlify-Source: dashboard-editor
… into editor-docs-overhaul
Brings all three translated sites onto the same nine-page structure as English instead of waiting for the translate automation, which has a documented history of leaving orphans behind. Content: - Deleted 21 orphans: branching-and-publishing, comments, configurations, git-essentials, live-preview, navigation, and suggestions in each language. None had an English source after the restructure. - Added publish, review, and collaborate in each language. - Rewrote index, pages, settings, agent, and keyboard-shortcuts to match the current English content, including Home/Publishing tabs, CodeMirror source mode, Show all files, and the restored Appearance section. - Kept the existing conventions: es uses usted, fr uses vous, keywords and product UI labels stay in English, and every heading is wrapped in a <div id="english-slug"> so cross-language anchors resolve. Verified that every English anchor exists in all three languages. Navigation and redirects: - es.json, fr.json, and zh.json now list the same nine pages as docs.json. - Removed six locale redirects that would have shadowed the new publish and collaborate pages once they existed. - Added 21 locale redirects for the removed pages and retargeted the destinations that pointed at them. - Retargeted four /editor/configurations redirects that pointed at #site-configurations, an anchor dropped in the settings rewrite. - Rewrote stale links in changelog, authentication-setup, concepts, and glossary across all three languages, since broken-links does not follow redirects. English fixes needed first, all caused by the settings restructure: - Restored ## Appearance. Two pages link to #appearance, and its four preferences were otherwise undocumented. - Restored ## Create draft pull requests by default, which changelog links to and which defaults to on. - Promoted Main branch autocommits from ### to ##; it was nested under PR instructions, and its warning named a setting no longer on the page. - Retargeted publish.mdx from the removed #auto-publish anchor. - Fixed a missing space in the settings page intro. mint broken-links clean, mint a11y clean (1042 files), vale 0 errors, all five JSON files valid. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation changes
Brief description of what's being updated
Closes
For Reviewers
When reviewing documentation PRs, please consider:
✅ Technical accuracy
✅ Clarity and completeness
✅ User experience
Mintlify
0 threads from 0 users in Mintlify
Note
Low Risk
Documentation-only reorganization and link updates; no application code changes.
Overview
Restructures the Editor docs around three workflows—Publish, Review, and Collaborate—and slims the sidebar in
docs.json(andes.json) by dropping standalone pages for git essentials, navigation, live preview, branching/publishing, comments, suggestions, and site configurations.Consolidates and rewrites content: removed long guides are split or merged into
editor/publish,editor/review, andeditor/collaborate; the overview (editor/index), pages guide, agent doc, and settings are rewritten for the Home / Publishing sidebar model and inline Git concepts;editor/pagesnow covers editing, navigation, and media in one place. The Configurations panel doc is removed entirely.Updates cross-links and release notes in
changelog.mdx,deploy/authentication-setup.mdx, and Spanish equivalents so paths point at/editor/publish,/editor/review#live-preview, and/editor/collaborate#…instead of the old URLs.Keyboard shortcuts doc now describes CodeMirror (not Monaco), adds Show all files and heading 5–6 shortcuts, and removes diff/sidebar toggles that no longer apply.
Minor Vale vocabulary tweaks for
autocommit,autosave, anddotfile.Reviewed by Cursor Bugbot for commit 74af83f. Bugbot is set up for automated code reviews on this repo. Configure here.