Web Editor

Build your documentation using the Mintlify web editor

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.

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 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.

Editor Modes

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.

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.

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 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.

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 Markdown mode. Changes are automatically saved as drafts.
4. Preview changes: See how your changes will appear in visual mode.

Publishing

Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.

When you’re ready to make your changes live, click the Publish button in the top-right corner of the web editor.

Your changes will be deployed to your production site immediately.

Branches

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. 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

1. Select the current branch name in the editor toolbar.
2. Select the branch that you want to switch to from the dropdown menu.

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 working on a branch, your changes are not automatically saved.

Pull Requests

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 on a Branch

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

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 the pull request into your main branch and the changes will be deployed 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 or GitLab integration.

• Automatic fetching: When you open the editor, it automatically fetches the latest content from your repository’s main 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 main 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.

Git Terminology

Understanding the following terms can help you work more effectively with the web editor and the Git workflow.

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.

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.

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.

Pull Request

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.

Diff

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.

Troubleshooting

Here are solutions to common issues you might encounter with the web editor.

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.

Permission Errors When Publishing

Possible causes:

• Insufficient permissions to the Git repository
• 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 documentation.

Editor Loading Issues

Possible causes:

• Network connectivity problems
• Large documentation repositories

Solutions:

1. Check your internet connection.
2. Refresh the page and try again.
3. Contact support if the issue persists.