Web Editor is the preferred way to edit docs directly without having to open your IDE or run mintlify dev.

The editor includes key features to integrate directly into your existing Git workflow, like creating branches, Pull Requests, commits, and diffs for your current changes.

It also includes a fully editable experience for changing and adding content directly, even with custom components.

If you understand Git workflows and our integrations already, you can skip to here.

​
Git and Update Workflows

​
Git Basics

While Web Editor means you don’t need to go to GitHub or your command line to make changes, it’s still helpful to know the basics of Git.

Git terminology:

  • Repository: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub).

  • Commit: A snapshot of changes made to files in the repository.

  • Branch: A separate line of development. It’s a working copy of the code that allows you to work on changes without affecting the main version.

  • Pull Request: A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live.

​
Making Updates

In order to make updates to your docs, we include several buttons specifically to integrate with your Git workflow.

If you haven’t done so already, please install the Mintlify GitHub app to your GitHub account. You can find documentation here, or you can install the app in the GitHub App page of the dashboard.

1

Creating New Branches

To make changes to your docs, you might want to change from the main branch to avoid publishing directly to your main docs site.

To do this, you can open the branches modal on the top left of the editor.

From here, you can either switch to a different Git branch than main, or you can create a new branch by clicking the “New Branch” button.

After you create a new branch, you’ll automatically be switched, and all changes you make will be made to this new branch until you change branches again or reload the page.

By default, when you load the page again, you’ll default to the main branch.

As a best practice, you should always create a new branch to make changes so you can submit a Pull Request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we’ll try to open a Pull Request for you.

2

Making a Commit

To make a commit, you have two options, both of which appear on the top right of the editor:

If you’re on the main branch of your docs repository, you can push a commit directly to the repo by clicking the “Publish” button. You’ll see your changes reflect in your Git branch the next time you run git pull.

This will create the Pull Request for you on GitHub using the branch you selected onto your main branch.

3

Making a Pull Request

When you submit your changes for review, you can edit the title and description of the Pull Request. If you leave these fields empty, a default Mintlify title will be provided.

​
Editing Content

​
Slash Commands

The easiest way to add content in the editor is by using “Slash Commands”, which are commands you have access to after typing / in the “Visual Editor” mode:

As you type, you’ll see more options appear:

Command Filtering

​
Content Blocks

Here are the types of content blocks available to add in the “Visual Editor”:

​
Adding Images

You can add images to your page by typing /image and either clicking on the “Image” option or hitting ↓ + Enter on the “Image” option.

This will open up the image modal where you have the option to either upload a new image or use an existing image from the repository.

You can upload an image through the modal:

You can also preview an existing image before adding it.

​
Editing Images

To edit images, hover over the image to see the “Delete” and “Edit” buttons on the top right of the image.

Clicking the “Edit” button lets you modify the attributes of the image.

To update the source of an image to a new image that you haven’t yet uploaded, first delete the existing image, then add a new one using the instructions above.

​
Editor Modes

To offer maximum flexibility, the editor has three modes:

View Mode Toggle

​
Visual Editor

The “Visual Editor” is the typical WYSIWYG mode you’d see in something like Notion. It provides a fully editable view of your docs that reflects what the final page will look like on your main docs site.

​
Source Editor

The “Source Editor” allows you to edit your MDX files in code, similar to how you would in your IDE. While it offers less flexibility, as our components aren’t available for auto-complete, it has two unique advantages:

  1. It allows you to edit component props (see our limitations below), which is currently not available in “Visual Editor” mode.

  2. It allows you to correct syntax errors that might have appeared in your repository that might not be compatible with “Visual Editor” mode until fixed.

​
Diff View

The “Diff View” allows you to review changes made to a specific document before committing it to your repository.

This helps you see both your changes and any formatting changes made by the editor.

​
Current Limitations

We currently have a few limitations in the editor that we’re working to resolve.

​
Feedback

We welcome any bug reports, feature requests, or other general feedback. We’d love to hear how we can improve.

Email us at support@mintlify.com

Was this page helpful?