From 4d3f23e0f57ce01630f76d98aa17b628ea2bfdd4 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 14 May 2025 14:58:42 -0700
Subject: [PATCH 1/3] Update web editor page
---
editor.mdx | 218 +++++++++++++++++++++++------------------------------
1 file changed, 94 insertions(+), 124 deletions(-)
diff --git a/editor.mdx b/editor.mdx
index 3f818f824..874c74f1c 100644
--- 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
## 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:** 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.
-
+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.
### 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.
-### 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.
-## 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.
-### Available Components
-
-The component menu gives you access to all supported elements and components, including:
-
-
-
- Text, headings, blockquotes
-
-
- Ordered and unordered lists
-
-
- Tabs, accordions, cards
-
-
- Images, videos, frames
-
-
- Columns, grids
-
-
- Code blocks
-
-
-
## 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
+
+ Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.
+
-## 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.
-After publishing, your changes will be deployed to your production site.
-
-
- Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.
-
-
## 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.
+
+
+ Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
+
### 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.
-
- Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
-
+### 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**.
### 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.
-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.
-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.
-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.
-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.
@@ -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.
-
**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.
@@ -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.
@@ -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.
From a520d5da149a15bea15325629004f8c287bcf831 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 14 May 2025 15:07:05 -0700
Subject: [PATCH 2/3] Remove TODOs
---
editor.mdx | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/editor.mdx b/editor.mdx
index 874c74f1c..3b8699a70 100644
--- a/editor.mdx
+++ b/editor.mdx
@@ -3,7 +3,7 @@ title: 'Web editor'
description: 'Build your documentation using the Mintlify web editor'
icon: 'mouse-pointer-2'
---
-TODO:consider removing decorative images
+
## Introduction
-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.
+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.
-## Web editor vs. CLI
+### Web editor vs. CLI
-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.
+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.
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.
@@ -204,7 +204,7 @@ The web editor integrates with your Git repository, ensuring that all changes ar
* **Branching**: You can make changes directly to your main branch or to a separate branch, depending on your workflow preferences.
-* **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 from the web editor.
## Git Terminology
From 13babe28acdd744b82ad0ab3b990e8277f0eba74 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 14 May 2025 17:05:08 -0700
Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=92=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
editor.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/editor.mdx b/editor.mdx
index a7b78f25e..4d1896db1 100644
--- a/editor.mdx
+++ b/editor.mdx
@@ -24,9 +24,9 @@ The web editor offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience wh
### Web editor vs. CLI
-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.
+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.
-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.
+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.
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.