Editor updates

create/reusable-snippets.mdx

@@ -6,6 +6,10 @@ keywords: ["content snippets", "reusable content", "variables"]
 
 One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet is used.
 
+<Note>
+  Snippets are not currently supported in the web editor. To use snippets, edit your MDX files locally with the CLI or push snippet imports directly to your repository.
+</Note>
+
 ## How snippets work
 
 Snippets are any `.mdx`, `.md`, or `.jsx` files imported into another file. You can place snippet files anywhere in your project. 

docs.json

@@ -81,20 +81,20 @@
                 "icon": "pen-line",
                 "pages": [
                   {
-                    "group": "Web editor",
+                    "group": "Editor",
+                    "tag": "New",
                     "root": "editor/index",
                     "pages": [
-                      "editor/git-essentials",
+                      "editor/tutorial",
+                      "editor/branching-and-publishing",
+                      "editor/live-preview",
                       "editor/pages",
-                      "editor/media",
                       "editor/navigation",
-                      "editor/configurations",
-                      "editor/live-preview",
-                      "editor/collaborate",
-                      "editor/publish",
-                      "editor/keyboard-shortcuts"
+                      "editor/keyboard-shortcuts",
+                      "editor/configurations"
                     ]
                   },
+                  "editor-classic",
                   "create/text",
                   "create/code",
                   {

editor-classic.mdx

@@ -0,0 +1,41 @@
+---
+title: "Web editor"
+description: "The classic Mintlify web editor for creating and publishing documentation in your browser. Sunsetting May 7, 2026."
+keywords: ["editor", "visual editor", "web editor"]
+tag: "Classic"
+---
+
+<Warning>
+  The classic web editor fully deprecates on May 7, 2026.
+
+  The new editor is now available with real-time collaboration, automatic saving across devices, and improved syncing. See [Editor](/editor) for more information.
+</Warning>
+
+The web editor lets you create, edit, and publish documentation directly in your browser.
+
+## Editor modes
+
+The editor has two modes you can switch between using the toggle in the toolbar.
+
+**Visual mode** shows a live preview of your content as you type. Press <kbd>/</kbd> to insert components and media, or format text.
+
+**Markdown mode** gives you direct access to the MDX source of your pages. Use this for precise control over component properties and frontmatter.
+
+## Publish changes
+
+The branch you work on determines how the editor publishes your changes. If you have branch protection rules on your repository, the editor enforces them.
+
+- **Deployment branch**: Publishing updates your live site immediately.
+- **Feature branches**: Publishing creates a pull request for review before deploying to your live site.
+
+## Keyboard shortcuts
+
+| Command | macOS | Windows |
+| :--- | :--- | :--- |
+| **Search files** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Ctrl</kbd> + <kbd>K</kbd> |
+| **Bold** | <kbd>Cmd</kbd> + <kbd>B</kbd> | <kbd>Ctrl</kbd> + <kbd>B</kbd> |
+| **Italic** | <kbd>Cmd</kbd> + <kbd>I</kbd> | <kbd>Ctrl</kbd> + <kbd>I</kbd> |
+| **Underline** | <kbd>Cmd</kbd> + <kbd>U</kbd> | <kbd>Ctrl</kbd> + <kbd>U</kbd> |
+| **Code** | <kbd>Cmd</kbd> + <kbd>E</kbd> | <kbd>Ctrl</kbd> + <kbd>E</kbd> |
+| **Add link** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Ctrl</kbd> + <kbd>K</kbd> |
+| **Component menu** | <kbd>/</kbd> | <kbd>/</kbd> |

editor/branching-and-publishing.mdx

@@ -0,0 +1,175 @@
+---
+title: "Branching and publishing"
+description: "Understand how branches and protection rules determine what happens when you publish, and how to manage the full review and deployment workflow."
+keywords: ["editor", "branch", "publish", "pull request", "preview", "git", "merge", "deploy"]
+---
+
+The web editor autosaves everything as you type, but your changes are only live when you choose to publish them. 
+
+What happens when you publish depends on two things: **which branch you're on** and **whether that branch requires pull requests**.
+
+## Saving versus publishing
+
+**Saving** happens automatically. Your edits are stored on Mintlify's servers and persist across browser tabs, devices, and network interruptions.
+
+**Publishing** commits your changes to your Git repository. Click the **Publish** button in the toolbar to open the publish menu, save your changes as a Git commit, and create a pull request.
+
+The editor tracks the following as pending changes:
+
+- Content edits in pages
+- New or deleted pages
+- Navigation structure changes
+- Media uploads
+- Configuration updates
+
+## What happens when you publish
+
+The actions available when you click the publish button depend on your current branch and whether it has branch protection rules that require pull requests.
+
+| Branch type | Branch protection | Available actions |
+|-------------|-------------------|-------------------|
+| <Tooltip headline="Deployment branch" tip="The branch that publishes to your live documentation site, typically 'main'.">Deployment branch</Tooltip> | None | **Publish** directly to your live site |
+| Deployment branch | Pull requests required | **Create branch** to move changes to a new branch |
+| <Tooltip headline="Feature branch" tip="An isolated branch where you work on updates before merging to your deployment branch.">Feature branch</Tooltip> | None | **Save in branch**, **Create pull request** |
+| Feature branch | Pull requests required | **Save in branch**, **Create pull request** |
+
+- **Publish**: Commits and deploys your changes to your live site immediately.
+- **Save in branch**: Commits your changes to the feature branch without merging to your deployment branch.
+- **Create branch**: Moves your pending changes to a new feature branch when you're on a protected deployment branch.
+- **Create pull request**: Opens a pull request targeting your deployment branch.
+
+If there are no pending changes, the publish and save actions are disabled.
+
+<Note>
+  Your live site updates after Mintlify builds and deploys your changes. This typically takes 30 seconds to a few minutes. Check the deployment status on your [dashboard](https://dashboard.mintlify.com).
+</Note>
+
+## When to use a branch
+
+**Edit directly on your deployment branch** if you do not use a Git-based workflow.
+
+**Create a branch** when you use a docs-as-code workflow where each change to your content is made on a separate branch.
+
+## Create and switch branches
+
+### Create a branch
+
+1. Click the branch name in the editor toolbar.
+1. Click **Create new branch**.
+1. If you have pending changes, choose whether to bring them to the new branch or leave them on the current branch.
+1. Enter a name and click **Create branch**.
+
+<Tip>
+  Use descriptive branch names so you can easily identify them and other people understand what each branch is for.
+</Tip>
+
+### Switch branches
+
+1. Click the branch name in the toolbar.
+1. Search for or scroll to the branch you want.
+1. Click the branch to switch to it.
+
+<Note>
+  Switching branches while you have unpublished changes will prompt you to bring those changes to the new branch or leave them behind. Changes left behind remain on your original branch.
+</Note>
+
+## Preview your changes
+
+Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render exactly as they look when published.
+
+### Access and share a preview
+
+1. Click **Publish** in the editor toolbar.
+1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`.
+    <Frame>
+      <img src="/images/editor/preview-url-light.png" alt="Preview URL emphasized in the publish menu." className="block dark:hidden" />
+      <img src="/images/editor/preview-url-dark.png" alt="Preview URL emphasized in the publish menu." className="hidden dark:block" />
+    </Frame>
+
+Copy the URL and send it to reviewers. The preview updates automatically each time you save to the branch.
+
+### Restrict access to previews
+
+Preview URLs are publicly accessible by default. To restrict access to members of your Mintlify organization, enable preview authentication in the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.
+
+### Share editor links
+
+To invite a teammate to a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session.
+
+The URL format is:
+
+```text
+https://dashboard.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
+```
+
+For example: `https://dashboard.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`
+
+## Review and merge pull requests
+
+When a pull request is open for the current branch, the publish menu shows its review status:
+
+- **Approved**: The pull request has been approved and is ready to merge.
+- **Changes requested**: A reviewer has requested changes before the pull request can merge.
+- **Awaiting review**: The pull request is waiting for a reviewer.
+
+Click **View request** to open the pull request in your Git provider.
+
+When the pull request is approved, click **Merge and publish** to merge and deploy directly from the editor. The editor switches to your deployment branch after merging.
+
+<Tip>
+  Configure branch protection rules in your Git provider to require pull requests. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) in the GitHub docs or [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/) in the GitLab docs.
+</Tip>
+
+### Review changes before merging
+
+Click any changed file in the publish menu to open it in diff view and compare your branch against the published version. Files that can't display a diff, such as images or deleted files, appear in the list but aren't clickable.
+
+### Simultaneous publishing
+
+Only one publish can happen at a time per branch. If another team member publishes to the same branch, wait for the current publish to complete before trying again.
+
+### Commit messages
+
+When you publish, you can enter a commit message before confirming. If you leave it blank, the editor generates a message based on the files changed.
+
+## Resolve conflicts
+
+Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, when you and a teammate edited the same lines in a file or moved a file to different locations.
+
+The editor displays a warning when conflicts block publishing. Follow the prompts to choose which version of each conflicting section to keep.
+
+## Collaborate in real time
+
+When multiple people open the same page on the same branch, they edit together in real time. Each person's cursor and edits are visible to everyone, with avatars shown in the toolbar.
+
+- Changes from all collaborators merge automatically. Two people editing the same section won't create conflicts.
+- Undo only affects your own edits.
+- If you lose your connection, edits save locally and sync when you reconnect.
+
+When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the editor like any other collaborator. You see the agent's avatar in the toolbar and a live cursor at its most recent edit location. The cursor clears automatically after the agent finishes.
+
+## Git sync
+
+When someone pushes changes to your repository from outside the editor, the editor incorporates those changes automatically.
+
+Non-overlapping changes apply automatically. If a remote change and your local edit affect the same part of a page, the editor highlights the conflict so you can resolve it.
+
+## Commit signing
+
+Sign commits with your GitHub account by authorizing it in your [account settings](https://dashboard.mintlify.com/settings/account). Without authorization, the Mintlify GitHub App signs commits made in the web editor.
+
+## Git operations reference
+
+For reference, here is how editor actions map to underlying Git operations.
+
+| Action in the editor | Git operation |
+|---|---|
+| Edit a page | Changes auto-save to Mintlify servers. No Git commit yet. |
+| Publish on your deployment branch | `git commit` and `git push`. Triggers a deployment. |
+| Save in branch | `git commit` to the current feature branch. |
+| Create pull request | `git push` and opens a pull request against your deployment branch. |
+| Merge and publish | Merges the pull request and triggers a deployment. |
+| Create a branch | `git checkout -b <branch-name>` |
+| Switch branches | `git checkout <branch-name>` |
+| External push or CLI update | Incoming changes sync into the editor automatically using a three-way merge. |
+