Web Editor

Build your documentation using the Mintlify Web Editor

Introduction

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.

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.

Both workflows are fully integrated with your Git repository, so you can use them interchangeably.

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.

Editor Modes

The Web Editor offers two distinct 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.

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’re comfortable with Markdown/MDX syntax.

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.

To access the component menu, press the / key.

Available Components

The component menu gives you access to all supported elements and components, including:

Basic blocks

Text, headings, blockquotes

Lists and tables

Ordered and unordered lists

Interactive components

Tabs, accordions, cards

Media

Images, videos, frames

Layouts

Columns, grids

Code blocks

Code blocks

Making Changes

The Web Editor provides an intuitive interface for making changes.

Creating and Editing Files

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

When you’re ready to make your changes live, click the “Publish” button in the top-right corner to publish your changes.

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.

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”

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.

Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.

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

Creating Pull Requests

Pull requests provide a way to review changes before they’re merged 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”

Reviewing Pull Requests

Pull requests can be reviewed directly in your Git platform (GitHub, GitLab).

After the pull request is created, you can see the 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.

Git Synchronization

The Web Editor seamlessly 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 or GitLab integration.

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

4. Branching: Changes can be made directly to your main branch or to a separate feature branch, depending on your workflow preferences.

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

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