Update web editor page

ethanpalm · ethanpalm · commit 4d3f23e0f57c · 2025-05-14T14:58:42.000-07:00
diff --git a/editor.mdx b/editor.mdx
@@ -1,9 +1,9 @@
 ---
-title: 'Web Editor'
-description: 'Build your documentation using the Mintlify Web Editor'
+title: 'Web editor'
+description: 'Build your documentation using the Mintlify web editor'
 icon: 'mouse-pointer-2'
 ---
-
+TODO:consider removing decorative images
 <img
   className="block dark:hidden my-0 pointer-events-none"
   src="/images/editor/editor-light.png"
@@ -16,253 +16,223 @@ icon: 'mouse-pointer-2'
 />
 
 ## Introduction
-
-The Web Editor provides a visual interface for creating and managing your documentation without requiring local development tools or command-line knowledge.
+TODO: expand this into how and why to use the Web Editor
+The web editor provides a visual interface for creating and managing your documentation without requiring local development tools or command-line knowledge.
 
 It offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience while maintaining synchronization with your Git repository, making it the perfect solution for team collaboration and quick documentation updates.
 
-## Web Editor vs. CLI
-
-The Web Editor is a visual editor that allows you to create and manage your documentation directly in the browser.
+## Web editor vs. CLI
 
-The CLI is a command-line tool that allows you to create and manage your documentation locally. It's the recommended workflow for developers who want to integrate documentation into their code workflows.
+The web editor allows you to create and manage your documentation directly in your browser. You should use the web editor if you want to maintain your documentation in one place with one tool.
 
-Both workflows are fully integrated with your Git repository, so you can use them interchangeably.
+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.
 
-<Tip>
-  **Tip:** For teams with mixed technical abilities, we recommend using both approaches: developers can use the CLI workflow while content writers and product managers can use the Web Editor.
-</Tip>
+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
 
-The Web Editor offers two distinct 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 modes at any time using the toggle in the top right corner of the editor toolbar.
 
 <Frame>
   <img 
     src="/images/editor/mode-toggle-light.png" 
-    alt="Mode toggle in the Mintlify Web Editor" 
+    alt="Mode toggle icons highlighted in the Mintlify web editor" 
     className="block dark:hidden"
   />
   <img 
     src="/images/editor/mode-toggle-dark.png" 
-    alt="Mode toggle in the Mintlify Web Editor" 
+    alt="Mode toggle icons highlighted in the Mintlify web editor" 
     className="hidden dark:block"
   />
 </Frame>
 
 ### Visual Mode
 
-Visual Mode provides a rich WYSIWYG experience where you can see exactly how your documentation will appear as you create it.
+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.
 
 <Frame>
   <img 
     src="/images/editor/visual-mode-light.png" 
-    alt="Visual editing mode in the Mintlify Web Editor" 
+    alt="Visual editing mode in the Mintlify web editor" 
     className="block dark:hidden"
   />
   <img 
     src="/images/editor/visual-mode-dark.png" 
-    alt="Visual editing mode in the Mintlify Web Editor" 
+    alt="Visual editing mode in the Mintlify web editor" 
     className="hidden dark:block"
   />
 </Frame>
 
-### Markdown Mode
+#### Component Menu
+
+You can add content blocks and other components to your documentation in visual mode using the dropdown component menu.
 
-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're comfortable with Markdown/MDX syntax.
+1. Press the `/` key to open the component menu.
+2. Select a component from the menu.
 
 <Frame>
   <img 
-    src="/images/editor/markdown-mode-light.png" 
-    alt="Markdown editing mode in the Mintlify Web Editor" 
-    className="block dark:hidden"
+    src="/images/editor/component-menu-light.png" 
+    alt="The unfurled component menu emphasized in the Mintlify web editor" 
+    className="block dark:hidden" 
   />
   <img 
-    src="/images/editor/markdown-mode-dark.png" 
-    alt="Markdown editing mode in the Mintlify Web Editor" 
-    className="hidden dark:block"
+    src="/images/editor/component-menu-dark.png" 
+    alt="The unfurled component menu emphasized in the Mintlify web editor" 
+    className="hidden dark:block" 
   />
 </Frame>
 
-## Component Menu
-
-Unlike the CLI where you need to know the exact syntax to add a component, the Web Editor makes it easy to add various content blocks through its dropdown menu system.
+### Source Mode
 
-To access the component menu, press the `/` key.
+Source 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.
 
 <Frame>
   <img 
-    src="/images/editor/component-menu-light.png" 
-    alt="Component menu in the Mintlify Web Editor" 
-    className="block dark:hidden" 
+    src="/images/editor/markdown-mode-light.png" 
+    alt="Source mode in the Mintlify web editor" 
+    className="block dark:hidden"
   />
   <img 
-    src="/images/editor/component-menu-dark.png" 
-    alt="Component menu in the Mintlify Web Editor" 
-    className="hidden dark:block" 
+    src="/images/editor/markdown-mode-dark.png" 
+    alt="Source mode in the Mintlify Web Editor" 
+    className="hidden dark:block"
   />
 </Frame>
 
-### Available Components
-
-The component menu gives you access to all supported elements and components, including:
-
-<CardGroup>
-  <Card title="Basic blocks" icon="a-large-small" horizontal>
-    Text, headings, blockquotes
-  </Card>
-  <Card title="Lists and tables" icon="list" horizontal>
-    Ordered and unordered lists
-  </Card>
-  <Card title="Interactive components" icon="puzzle" horizontal>
-    Tabs, accordions, cards
-  </Card>
-  <Card title="Media" icon="image" horizontal>
-    Images, videos, frames
-  </Card>
-  <Card title="Layouts" icon="columns-2" horizontal>
-    Columns, grids
-  </Card>
-  <Card title="Code blocks" icon="code" horizontal>
-    Code blocks
-  </Card>
-</CardGroup>
-
 ## Making Changes
 
-The Web Editor provides an intuitive interface for making changes.
+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 source mode. Changes are automatically saved as drafts.
+4. **Preview changes**: See how your changes will appear in visual mode.
 
-### Creating and Editing Files
+## Publishing
 
-1. **Browse Files**: Use the sidebar file explorer to navigate through your documentation structure
-2. **Open a File**: Click on any file to open it in the editor
-3. **Make Changes**: Edit the content using Visual or Markdown mode
-4. **Preview Changes**: See how your changes will appear in real-time
-5. **Save Changes**: Changes are automatically saved as drafts
+<Info>
+  Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.
+</Info>
 
-## Publishing
+When you're ready to make your changes live, click the **Publish** button in the top-right corner of the web editor.
 
-When you're ready to make your changes live, click the "Publish" button in the top-right corner to publish your changes.
+Your changes will be deployed to your production site immediately.
 
 <Frame>
   <img 
     src="/images/editor/publish-flow-light.png" 
-    alt="Publishing flow in the Mintlify Web Editor" 
+    alt="The publish button emphasized in the Mintlify web editor" 
     className="block dark:hidden" 
   />
   <img 
     src="/images/editor/publish-flow-dark.png" 
-    alt="Publishing flow in the Mintlify Web Editor" 
+    alt="The publish button emphasized in the Mintlify web editor" 
     className="hidden dark:block" 
   />
 </Frame>
 
-After publishing, your changes will be deployed to your production site.
-
-<Info>
-  Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.
-</Info>
-
 ## Branches
 
-Branches allow you to work on documentation changes without affecting the main version until you're ready.
+Branches allow you to work on documentation changes without updating the main version until you're ready for your changes to go live.
+
+<Tip>
+  Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
+</Tip>
 
 ### Creating a Branch
 
-1. Click on the branch name in the editor toolbar (usually shows `main` by default)
-2. Select "Create a new branch"
-3. Enter a descriptive name for your branch
-4. Click "Create 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.
+4. Select **Create Branch**.
 
 ### Switching Branches
 
-To switch branches, you can click on the current branch name in the editor toolbar and select the branch you want to switch to from the dropdown menu.
+1. Select the current branch name in the editor toolbar.
+2. Select the branch that you want to switch to from the dropdown menu.
 
-<Tip>
-  Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
-</Tip>
+### 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. 
 
-When you are in a branch, you can make and save changes by clicking the "Save Changes" button in the top-right corner. These changes will be saved to the branch as "commits".
+When you are working on a branch, your changes are not automatically saved.
 
-## Creating Pull Requests
+## Pull Requests
 
-Pull requests provide a way to review changes before they're merged into your main documentation.
+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 main documentation.
 
 ### Creating a Pull Request
 
-1. Make your changes on a feature branch
-2. Click the "Create Pull Request" button in the top-right corner
-3. Add a title and description for your pull request
-4. Click "Create Pull Request"
+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**.
 
 <Frame>
   <img 
     src="/images/editor/pull-request-light.png" 
-    alt="Pull request creation in the Mintlify Web Editor" 
+    alt="Publish pull request button emphasized in the Mintlify web editor" 
     className="block dark:hidden" 
   />
   <img 
     src="/images/editor/pull-request-dark.png" 
-    alt="Pull request creation in the Mintlify Web Editor" 
+    alt="Publish pull request button emphasized in the Mintlify web editor" 
     className="hidden dark:block" 
   />
 </Frame>
 
 ### Reviewing Pull Requests
 
-Pull requests can be reviewed directly in your Git platform (GitHub, GitLab).
+You can review pull requests in your Git platform (GitHub, GitLab).
 
-After the pull request is created, you can see the preview deployment of the changes.
+After you create a pull request, you can see a preview deployment of the changes.
 
-Upon approval, the pull request can be merged into your main branch and the changes will be deployed to your production site.
+After a reviewer approves a pull request, you can merge the pull request into your main branch and the changes will be deployed to your live documentation site.
 
 ## Git Synchronization
 
-The Web Editor seamlessly integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
+The web editor integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
 
 ### How Git Sync Works
 
-1. **Authentication**: The Web Editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
+* **Authentication**: The web editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
 
-2. **Automatic Fetching**: When you open the editor, it automatically fetches the latest content from your repository's main branch.
+* **Automatic fetching**: When you open the editor, it automatically fetches the latest content from your repository's main branch.
 
-3. **Change Tracking**: As you make edits in the Web Editor, changes are tracked and can be committed to your repository.
+* **Change tracking**: As you make edits, the web editor tracks changes and can commit them to your repository.
 
-4. **Branching**: Changes can be made directly to your main branch or to a separate feature branch, depending on your workflow preferences.
+* **Branching**: You can make changes directly to your main branch or to a separate branch, depending on your workflow preferences.
 
-5. **Pull Requests**: For collaborative workflows, you can create pull requests directly from the Web Editor.
+* **Pull requests**: For collaborative workflows, you can create pull requests directly from the web editor.
 
 ## Git Terminology
 
-While not necessary, understanding the following terms will help you work more effectively with the Web Editor.
-
-The following terms are used in the Web Editor and are also used in the Git workflow.
+Understanding the following terms can help you work more effectively with the web editor and the Git workflow.
 
 <AccordionGroup>
 
 <Accordion title="Repository">
 
-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 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.
 
 </Accordion>
 
 <Accordion title="Commit">
 
-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.
+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.
 
 </Accordion>
 
 <Accordion title="Branch">
 
-A branch is a parallel version of your documentation that allows you to work on changes without affecting the main version. The Web Editor allows you to create and switch between branches.
+A branch is a parallel version of your documentation that allows you to work on changes without affecting the main version. The web editor allows you to create and switch between branches.
 
 </Accordion>
 
 <Accordion title="Pull Request">
 
-A pull request (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.
+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.
 
 </Accordion>
 
@@ -276,19 +246,19 @@ A diff (or difference) shows the specific changes between two versions of a file
 
 ## Troubleshooting
 
-Here are solutions to common issues you might encounter with the Web Editor.
+Here are solutions to common issues you might encounter with the web editor.
 
 <AccordionGroup>
 <Accordion title="Changes Not Appearing After Publishing">
-
 **Possible causes:**
+
 - Deployment is still in progress
 - Caching issues in your browser
 
 **Solutions:**
-1. Check deployment status in your Mintlify Dashboard
-2. Try hard refreshing your browser (Ctrl+F5 or Cmd+Shift+R)
-3. Clear your browser cache
+1. Check the deployment status in your Mintlify Dashboard.
+2. Try hard refreshing your browser (Ctrl+F5 or Cmd+Shift+R).
+3. Clear your browser cache.
 
 </Accordion>
 
@@ -299,9 +269,9 @@ Here are solutions to common issues you might encounter with the Web Editor.
 - Authentication issues with your Git provider
 
 **Solutions:**
-1. Verify you have correct access to the repository
-2. Check if your Git integration is properly configured
-3. Review the [Editor Permissions](/advanced/dashboard/permissions) documentation
+1. Verify that you have correct access to the repository.
+2. Check if your Git integration is properly configured.
+3. Review the [Editor Permissions](/advanced/dashboard/permissions) documentation.
 
 </Accordion>
 
@@ -312,9 +282,9 @@ Here are solutions to common issues you might encounter with the Web Editor.
 - Large documentation repositories
 
 **Solutions:**
-1. Check your internet connection
-2. Refresh the page and try again
-3. Contact support if the issue persists
+1. Check your internet connection.
+2. Refresh the page and try again.
+3. Contact support if the issue persists.
 
 </Accordion>
 </AccordionGroup>
