Web editor

Mintlify web editor interface in light mode

Mintlify web editor interface in dark mode

Access the web editor from your dashboard to manage your documentation directly in your browser.

WYSIWYG editing: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published.
Git synchronization: All changes automatically sync with your Git repository to maintain version control.
Team collaboration: Multiple people can work on documentation simultaneously.
Component integration: Add callouts, code blocks, and other components with slash commands.
No setup required: Start writing immediately from your dashboard.

Overview

Here is how you’ll typically work in the web editor:

Choose your branch

Create a branch or make changes directly to your deployment branch. We recommend creating a branch so that you can preview your changes before they go live.

Open your file

Navigate to an existing file in the sidebar or create a new one using the file explorer.

Edit your content

Make changes in the web editor. Press / to open the component menu.

Preview your changes

Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct.

Publish your changes

Publish your changes directly to your live documentation site or create a pull request to review changes before merging.

Editor modes

The web editor has two modes to accommodate different editing preferences and needs: visual mode and Markdown mode. Use the mode toggle in the editor toolbar to switch modes.

Mode toggle icons highlighted in the web editor.

Visual mode

Visual mode provides a WYSIWYG experience where changes that you make in the editor reflect how your published documentation will look. This mode is ideal for when you want to see how your changes will look in real-time.

Visual editing mode in the Mintlify web editor.

Markdown mode

Markdown mode provides direct access to the files that make up your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in MDX syntax.

Manage content

Navigate your files

Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor. Press Command + P on macOS or Ctrl + P on Windows to search for files by name.

Create new pages

Select the Create a new file icon in the file explorer sidebar.

Files menu in the web editor in dark mode.

Filenames are automatically appended with a .mdx extension. To change the file type, click the file extension. Select the file type you want from the dropdown menu.

File extension menu in the web editor in dark mode.

Rename pages

To rename a page, click the kebab menu icon for the file you want to rename. Select Rename from the dropdown menu.

Rename page in the web editor in dark mode.

Delete pages

To delete a page, click the kebab menu icon for the file you want to delete. Select Delete from the dropdown menu.

Delete page in the web editor in dark mode.

Edit your docs.json file to add new pages and remove deleted pages from your site navigation. See Navigation for more information on how to organize pages. Example: Add a Themes page to the Profile group In this example, you created a new page titled Themes and you want to add it to the Profile group in your documentation. Add the path to the new page to the pages array of the Profile group in your docs.json file for it to appear in your site navigation.

Adding a Themes page to the Profile group

{
    "navigation": {
        "groups": [
            {
                "group": "Getting started",
                "pages": [
                    "index",
                    "quickstart",
                    "installation"
                ]
            },
            {
                "group": "Profile",
                "pages": [
                    "settings",
                    "account-types",
                    "dashboard",
                    "themes"
                ]
            }
        ]
    }
}

Edit content

Make changes to your pages using visual mode or Markdown mode in the editor. In visual mode, press / to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation.

The unfurled component menu emphasized in the Mintlify web editor.

In Markdown mode, you can directly edit the MDX of your pages. This can be helpful when you need to:

Set specific component properties
Work with complex nested components
Copy and paste MDX content from other sources

See Format text and Format code for more information on how to write using MDX syntax.

Publish your changes

The editor’s publishing workflow depends on which branch you work on and your repository’s branch protection rules.

Branch type	Branch protection	What happens when you publish
Deployment branch	None	Changes merge and are live immediately
Deployment branch	Pull requests required	Creates a pull request for review
Other branch	None	Changes merge into deployment branch and are live immediately
Other branch	Pull requests required	Creates a pull request for review

Configure branch protection rules in your Git provider to require pull request reviews before merging. See About protected branches in the GitHub docs or Protected branches in the GitLab docs for more information.

The publish button emphasized in the Mintlify web editor.

To sign commits with your GitHub account, you must authorize your GitHub account on the My profile page of your dashboard. If you don’t authorize your GitHub account, the Mintlify GitHub App signs commits made in the web editor.

Pull requests and reviewing changes

Pull requests let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content.

Even if you’re working solo, pull requests are valuable for previewing changes and maintaining a clear history of updates.

Create a pull request

Save your work

Select Save Changes to save all changes on your branch.

Create the pull request

Select Publish Pull Request from the editor toolbar.

Add a title and description

Write a clear title and description explaining:

What changes you made
Why you made them
Any specific areas that need review

Create and share

Select Publish Pull Request. The editor provides a link to view your pull request.

Publish pull request button emphasized in the Mintlify web editor.

Review pull requests

Once your pull request is created:

Review changes: You and your team members can review your pull request in your Git provider like GitHub or GitLab.
Leave feedback: Add comments or request changes.
Make additional changes: Make additional changes in the web editor. When you save changes, the editor pushes them to your pull request.
Approve: Approve the pull request when you’re satisfied with the changes.
Merge: Merge the pull request when you’re ready to deploy your changes to production.

Share preview deployments with your team to gather feedback before you publish changes.

Click the Share button in the editor toolbar.
Click the Preview button to open the preview deployment in a new browser tab.
Share the preview URL with anyone who needs to review your changes.

When you make changes, the preview deployment updates automatically. Changes may take a short time to appear. Preview URLs are publicly accessible by default. Anyone with the link can view your preview deployment. To restrict access to authenticated members of your organization, enable preview authentication in your dashboard.

Keyboard shortcuts

The web editor supports all common keyboard shortcuts such as copy, paste, undo, and select all, and the following shortcuts:

Command	macOS	Windows
Search files	`Cmd` + `P`	`Control` + `P`
Add link to highlighted text	`Cmd` + `K`	`Control` + `K`
Add line break	`Cmd` + `Enter`	`Control` + `Enter`
Bold	`Cmd` + `B`	`Control` + `B`
Italic	`Cmd` + `I`	`Control` + `I`
Underline	`Cmd` + `U`	`Control` + `U`
Strikethrough	`Cmd` + `Shift` + `S`	`Control` + `Shift` + `S`
Code	`Cmd` + `E`	`Control` + `E`
Normal text	`Cmd` + `Alt` + `0`	`Control` + `Alt` + `0`
Heading 1	`Cmd` + `Alt` + `1`	`Control` + `Alt` + `1`
Heading 2	`Cmd` + `Alt` + `2`	`Control` + `Alt` + `2`
Heading 3	`Cmd` + `Alt` + `3`	`Control` + `Alt` + `3`
Heading 4	`Cmd` + `Alt` + `4`	`Control` + `Alt` + `4`
Ordered list	`Cmd` + `Shift` + `7`	`Control` + `Shift` + `7`
Unordered list	`Cmd` + `Shift` + `8`	`Control` + `Shift` + `8`
Blockquote	`Cmd` + `Shift` + `B`	`Control` + `Shift` + `B`
Subscript	`Cmd` + `,`	`Control` + `,`
Superscript	`Cmd` + `.`	`Control` + `.`

Troubleshooting

Find solutions to common issues you might encounter while using the web editor.

Changes not appearing after publishing

Possible causes:

Deployment is still in progress
Browser caching issues
Build or deployment errors

Solutions:

Check deployment status in your dashboard.
Hard refresh your browser (Ctrl
or Cmd
)
Clear your browser cache.

Permission errors when publishing

Possible causes:

Insufficient permissions to the Git repository
Authentication issues with your Git provider

Solutions:

Verify you have correct access to the repository.
Check if your Git integration is properly configured.
Review the Editor Permissions documentation.

Editor loading issues

Possible causes:

Network connectivity problems
Large documentation repositories

Solutions:

Check your internet connection.
Refresh the page.
Contact support if the issue persists.

Files not loading or showing errors

Possible causes:

Invalid MDX syntax in files
Missing or corrupted files
Large file sizes causing timeouts

Solutions:

Check the file syntax for MDX formatting errors
Verify the file exists in your repository.

Next steps

Learn fundamental Git concepts
Learn best practices for collaborating with branches

Get started

Organize

Customize

Create content

Document APIs

Deploy

Optimize

Overview