diff --git a/editor.mdx b/editor.mdx
index 524a105ba..3c7d23df2 100644
--- a/editor.mdx
+++ b/editor.mdx
@@ -7,34 +7,51 @@ icon: "mouse-pointer-2"
## Introduction
The web editor is a visual interface for creating, editing, and reviewing documentation directly in your browser.
-The web editor offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience while maintaining synchronization with your Git repository, which lets you see updates in real time and collaborate with your team on documentation changes.
+- **Visual editing**: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published.
+- **Git synchronization**: All changes automatically sync with your Git repository to maintain version control.
+- **Real-time collaboration**: Multiple team members can work on documentation simultaneously, with changes visible to everyone.
+- **No setup required**: Start writing immediately from your dashboard.
-### Web editor vs. CLI
+### Web editor flow
-The web editor lets you write and edit your documentation in your browser without requiring local development tools or using the command line. You should use the web editor if you want to maintain your documentation in one place with one tool.
+Here is how you'll typically work in the web editor:
-The CLI is a command line tool that allows you to create and manage your documentation locally using the IDE of your choice. You should use the CLI if you want to integrate documentation into your existing development workflow.
+
+
+ Create a branch or make changes directly to your deployment branch.
+
+
+ Navigate to an existing file or create a new one.
+
+
+ Make changes in the web editor using either visual mode or Markdown mode.
+
+
+ See how your changes will appear in visual mode.
+
+
+ If you're working on your deployment branch, publish your changes directly from the web editor. On other branches, publish your changes through a pull request.
+
+
-Both the web editor and CLI are fully integrated with your Git repository, so you can use them interchangeably and different members of your team can use either tool based on their preferences.
+## Editor modes
-## Editor Modes
+The web editor has two modes to accommodate different editing preferences and needs.
-The web editor offers two modes to accommodate different editing preferences and needs.
-
-You can switch between natural modes at any time using the toggle in the top right corner of the editor toolbar.
+You can switch between modes at any time using the toggle in the top right corner of the editor toolbar.
![]()
-### Visual Mode
+### Visual mode
Visual mode provides a WYSIWYG experience where the changes that you make in the editor are the changes that will be published to your documentation site. This mode is ideal for when you want to see how your changes will look in real-time.
@@ -66,29 +83,9 @@ Visual mode provides a WYSIWYG experience where the changes that you make in the
/>
-#### Component Menu
-
-You can add content blocks and other components to your documentation in visual mode using the dropdown component menu.
-
-1. Press the `/` key to open the component menu.
-2. Select a component from the menu.
-
-
- 
- 
-
-
-### Markdown Mode
+### Markdown mode
-Markdown mode provides direct access to the underlying MDX code of your documentation. This mode is preferable when you need precise control over component properties or when you prefer to write in Markdown/MDX syntax.
+Markdown mode provides direct access to the underlying `MDX` code of your documentation. `MDX` combines Markdown syntax with React components, giving you full control over your content structure. This mode is ideal for when you need precise control over component properties or when you prefer to write in Markdown syntax.
![]()
-## Making Changes
+## Git fundamentals
-1. **Browse files**: Use the sidebar file explorer to navigate through your documentation.
-2. **Open a file**: Click on the file that you want to edit to open it in the editor.
-3. **Make changes**: Edit the content using visual or Markdown mode. Changes are automatically saved as drafts.
-4. **Preview changes**: See how your changes will appear in visual mode.
+The web editor performs Git operations behind the scenes. Understanding these concepts will help you work more effectively with the web editor and collaborate with team members who are working in their local environments.
-## Publishing
+
+
+ Your documentation's source where all files and their history are stored. The web editor connects to your repository to access and modify content.
+
-The **Publish** button works differently depending on your branch:
+
+ A saved snapshot of your changes at a specific point in time.
+
-* **Deployment branch**: Updates your live site immediately. This is usually the `main` branch.
-* **Other branches**: Creates a pull request for review.
+
+ A separate workspace for making changes without affecting your live documentation. Think of it as a safe sandbox for experiments and larger updates.
+
-
- 
- 
-
+
+ The main branch that contains your live documentation content. Changes to this branch are automatically published to your documentation site. Often called `main`.
+
+
+
+ A way to propose merging your branch changes into your live documentation. Allows for review and discussion before changes go live.
+
-## Branches
+
+ A diff (or difference) shows the specific changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified.
+
+
-Branches allow you to safely work on changes without affecting your live documentation. When your changes are ready, you can merge them into your deployment branch with a pull request.
+### What the web editor automates
-
- Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
-
+The web editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab) and handles Git automatically. When you:
+
+- **Open a file**: Fetches the latest version from your repository.
+- **Make changes in a file**: Tracks your changes as a draft that can become a commit.
+- **Save changes**: Creates a commit with your changes.
+- **Create a branch**: Creates a new branch in your repository.
+- **Publish on your deployment branch**: Creates a commit and pushes directly to your deployment branch.
+- **Publish on other branches**: Creates a commit and opens a pull request.
+
+### When to use branches
-### Creating a Branch
+Branches let you work on changes without affecting the content on your live site. When your changes are ready, you can merge them into your deployment branch with a pull request.
+
+**Best practice: Always work from branches.** This ensures your live documentation stays stable and enables proper review workflows.
+
+## Creating a branch
1. Select the branch name in the editor toolbar (usually `main` by default).
2. Select **New Branch**.
-3. Enter a descriptive name for your branch.
+3. Enter a descriptive name for your branch like `update-getting-started` or `fix-installation-steps`.
4. Select **Create Branch**.
-### Switching Branches
+
+ You may need to select your new branch from the dropdown menu if the editor does not automatically switch to it.
+
+
+### Saving changes on a branch
+
+To save your changes on a branch, select the **Save Changes** button in the top-right corner of the editor. This creates a commit with your changes and pushes it to your branch.
+
+### Switching branches
1. Select the current branch name in the editor toolbar.
-2. Select the branch that you want to switch to from the dropdown menu.
+2. Select the branch you want to switch to from the dropdown menu.
-### Saving Changes on a Branch
+
+ Any unsaved changes will be lost when switching branches. Make sure to save or publish your work before switching.
+
-To save your changes on a branch, select the **Save Changes** button in the top-right corner of the editor.
+## Making changes
-When you are working on a branch, your changes are not automatically saved.
+Edit existing content, create new pages, and organize your site structure in the web editor.
-## Pull Requests
+### Navigating files
-Pull requests (or PRs) let you and other people review changes that you've made on a branch and then merge those changes into your documentation.
+Use the sidebar file explorer to browse your documentation, or press Command + P (Ctrl + P on Windows) to search for files.
-### Creating a Pull Request on a Branch
+### Editing content
-1. Make your changes on a branch.
-2. Click the **Publish Pull Request** button in the top-right corner of the editor.
-3. Add a Pull Request Title and Description for your pull request. A good title and description will help reviewers understand the changes you've made.
-4. Click **Publish Pull Request**.
+Make changes to your pages using visual mode or Markdown mode.
+
+In visual mode, press / to open the dropdown component menu. Add content blocks, callouts, code blocks and other components to customize your documentation.
-### Reviewing Pull Requests
-
-You can review pull requests in your Git platform (GitHub, GitLab).
-
-After you create a pull request, you can see a preview deployment of the changes.
-
-After a reviewer approves a pull request, you can merge it to deploy the changes to your live documentation site.
-
-## Git Synchronization
-
-The web editor integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
-
-### How Git Sync Works
-
-* **Authentication**: The web editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
-
-* **Automatic fetching**: When you open the editor, it automatically fetches the latest content from your repository's deployment branch.
-
-* **Change tracking**: As you make edits, the web editor tracks changes and can commit them to your repository.
-
-* **Branching**: You can make changes directly to your deployment branch or to a separate branch, depending on your workflow preferences.
-
-* **Pull requests**: For collaborative workflows, you can create pull requests from the web editor.
+### Creating new pages
+
+1. Select the **Create a new file** icon in the file explorer.
+ 
+ 
+1. Enter a filename.
+1. Press Enter to create the file.
+
+Your new page will open in the editor, ready for content to be added.
+
+### Updating navigation
+
+Add, remove, and reorder pages in your navigation by editing your `docs.json` file:
+
+1. Navigate to your `docs.json` in the file explorer.
+1. Update the `navigation` property to get the navigation structure that you want. See [Navigation](/navigation) for more information.
+
+This example shows how to add a Themes page to the Profile group.
+
+```json title="Adding a Themes page" highlight="18"
+{
+ "navigation": {
+ "groups": [
+ {
+ "group": "Getting started",
+ "pages": [
+ "index",
+ "quickstart",
+ "installation"
+ ]
+ },
+ {
+ "group": "Profile",
+ "pages": [
+ "settings",
+ "account-types",
+ "dashboard",
+ "themes"
+ ]
+ }
+ ]
+ }
+}
+```
+
+## Publishing changes
+
+Select the **Publish** button to save your changes and make them available.
+
+How your changes are published depends on which branch you are working on:
+
+* **Deployment branch**: Updates your live site immediately.
+* **Other branches**: Creates a pull request so you can review changes before they go live.
-## Git Terminology
-
-Understanding the following terms can help you work more effectively with the web editor and the Git workflow.
-
-
-
-
-
-A repository (or repo) is where your documentation files are stored, along with their revision history. The web editor connects to your Git repository to fetch and store documentation content.
-
-
-
-
-
-A commit is a snapshot of changes to your documentation at a specific point in time. When you publish changes in the web editor, you're creating a commit in your Git repository.
+
+
+
+
-
+## Pull Requests and reviewing changes
-
+Pull requests (PRs) let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content.
-A branch is a parallel version of your documentation that allows you to work on changes without affecting the live version. The web editor allows you to create and switch between branches.
+
+ Even if you're working solo, pull requests are valuable for previewing changes before they go live and maintaining a clear history of updates.
+
-
+### Creating a pull request on a branch
-
+When you're ready to publish changes from your branch:
-A pull request (or PR) is a proposal to merge changes from one branch into another, typically from a feature branch into the main branch. PRs facilitate review and discussion before changes are incorporated.
+1. Make sure all your changes are saved on your branch.
+1. Select **Publish Pull Request** in the top-right corner of the editor.
+1. Add a title and description for your pull request. A good title and description help reviewers understand the changes you've made.
+1. Select **Publish Pull Request**.
-
+
+
+
+
-
+The web editor will create a pull request in your Git repository and provide a link to view it.
-A diff (or difference) shows the specific changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified.
+### Reviewing pull requests
-
+Once your pull request is created:
-
+1. **Review your changes**: You and your team members can review your pull request in your Git provider like GitHub or GitLab.
+1. **Make additional changes**: After reviewing, make any changes in your web editor. Saving your changes will update your pull request.
+1. **Merge when ready**: When your pull request is ready, merge it to deploy changes to your live documentation site.
## Troubleshooting
Here are solutions to common issues you might encounter with the web editor.
-
+
**Possible causes:**
- Deployment is still in progress
@@ -256,10 +333,10 @@ Here are solutions to common issues you might encounter with the web editor.
**Solutions:**
1. Check deployment status in your Mintlify Dashboard.
- 2. Try hard refreshing your browser (Ctrl\+F5 or Cmd\+Shift\+R).
+ 2. Try hard refreshing your browser (Ctrl + F5 or Cmd + Shift + R).
3. Clear your browser cache.
-
+
**Possible causes:**
- Insufficient permissions to the Git repository
@@ -271,7 +348,7 @@ Here are solutions to common issues you might encounter with the web editor.
2. Check if your Git integration is properly configured.
3. Review the [Editor Permissions](/advanced/dashboard/permissions) documentation.
-
+
**Possible causes:**
- Network connectivity problems
diff --git a/images/editor/files-menu-dark.png b/images/editor/files-menu-dark.png
new file mode 100644
index 000000000..51f4267a4
Binary files /dev/null and b/images/editor/files-menu-dark.png differ
diff --git a/images/editor/files-menu-light.png b/images/editor/files-menu-light.png
new file mode 100644
index 000000000..e3936f754
Binary files /dev/null and b/images/editor/files-menu-light.png differ
diff --git a/quickstart.mdx b/quickstart.mdx
index 3dd52da63..091f3826d 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -158,7 +158,7 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf
### Access the Web Editor
-1. Log in to your [Mintlify Dashboard](https://dashboard.mintlify.com).
+1. Log in to your [dashboard](https://dashboard.mintlify.com).
2. Select **Editor** on the left sidebar.
@@ -174,9 +174,9 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf
In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
-Find and click on `introduction.mdx` in the file explorer.
+Find and select `introduction.mdx` in the file explorer.
-Then, in the visual editor, update the title field to "Hello World".
+Then, in the editor, update the title field to "Hello World".
@@ -192,10 +192,10 @@ Then, in the visual editor, update the title field to "Hello World".
When you are satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site.
-Use branches to preview and review changes through pull requests before deploying to your live site.
+ Use branches to preview and review changes through pull requests before deploying to your live site.
-For more details about using the web editor, including using branches and pull request to collaborate and preview changes, see our [Web Editor documentation](/editor).
+For more details about using the web editor, including using branches and pull request to collaborate and preview changes, see our [web editor documentation](/editor).
## Adding a Custom Domain