Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions create/reusable-snippets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ keywords: ["content snippets", "reusable content", "variables"]

One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet is used.

<Note>
Snippets are not currently supported in the web editor. To use snippets, edit your MDX files locally with the CLI or push snippet imports directly to your repository.
</Note>

## How snippets work

Snippets are any `.mdx`, `.md`, or `.jsx` files imported into another file. You can place snippet files anywhere in your project.
Expand Down
16 changes: 8 additions & 8 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -81,20 +81,20 @@
"icon": "pen-line",
"pages": [
{
"group": "Web editor",
"group": "Editor",
"tag": "New",
"root": "editor/index",
"pages": [
"editor/git-essentials",
"editor/tutorial",
"editor/branching-and-publishing",
"editor/live-preview",
"editor/pages",
"editor/media",
"editor/navigation",
"editor/configurations",
"editor/live-preview",
"editor/collaborate",
"editor/publish",
"editor/keyboard-shortcuts"
"editor/keyboard-shortcuts",
"editor/configurations"
]
},
"editor-classic",
"create/text",
"create/code",
{
Expand Down
41 changes: 41 additions & 0 deletions editor-classic.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: "Web editor"
description: "The classic Mintlify web editor for creating and publishing documentation in your browser. Sunsetting May 7, 2026."

Check warning on line 3 in editor-classic.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor-classic.mdx#L3

Did you really mean 'Sunsetting'?
keywords: ["editor", "visual editor", "web editor"]
tag: "Classic"
---

<Warning>
The classic web editor fully deprecates on May 7, 2026.

The new editor is now available with real-time collaboration, automatic saving across devices, and improved syncing. See [Editor](/editor) for more information.
</Warning>

The web editor lets you create, edit, and publish documentation directly in your browser.

## Editor modes

The editor has two modes you can switch between using the toggle in the toolbar.

**Visual mode** shows a live preview of your content as you type. Press <kbd>/</kbd> to insert components and media, or format text.

**Markdown mode** gives you direct access to the MDX source of your pages. Use this for precise control over component properties and frontmatter.

## Publish changes

The branch you work on determines how the editor publishes your changes. If you have branch protection rules on your repository, the editor enforces them.

- **Deployment branch**: Publishing updates your live site immediately.
- **Feature branches**: Publishing creates a pull request for review before deploying to your live site.

## Keyboard shortcuts

| Command | macOS | Windows |
| :--- | :--- | :--- |
| **Search files** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Ctrl</kbd> + <kbd>K</kbd> |
| **Bold** | <kbd>Cmd</kbd> + <kbd>B</kbd> | <kbd>Ctrl</kbd> + <kbd>B</kbd> |
| **Italic** | <kbd>Cmd</kbd> + <kbd>I</kbd> | <kbd>Ctrl</kbd> + <kbd>I</kbd> |
| **Underline** | <kbd>Cmd</kbd> + <kbd>U</kbd> | <kbd>Ctrl</kbd> + <kbd>U</kbd> |
| **Code** | <kbd>Cmd</kbd> + <kbd>E</kbd> | <kbd>Ctrl</kbd> + <kbd>E</kbd> |
| **Add link** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Ctrl</kbd> + <kbd>K</kbd> |
| **Component menu** | <kbd>/</kbd> | <kbd>/</kbd> |
175 changes: 175 additions & 0 deletions editor/branching-and-publishing.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
---
title: "Branching and publishing"
description: "Understand how branches and protection rules determine what happens when you publish, and how to manage the full review and deployment workflow."
keywords: ["editor", "branch", "publish", "pull request", "preview", "git", "merge", "deploy"]
---

The web editor autosaves everything as you type, but your changes are only live when you choose to publish them.

Check warning on line 7 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L7

Did you really mean 'autosaves'?

What happens when you publish depends on two things: **which branch you're on** and **whether that branch requires pull requests**.

## Saving versus publishing

**Saving** happens automatically. Your edits are stored on Mintlify's servers and persist across browser tabs, devices, and network interruptions.

Check warning on line 13 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L13

In general, use active voice instead of passive voice ('are stored').

**Publishing** commits your changes to your Git repository. Click the **Publish** button in the toolbar to open the publish menu, save your changes as a Git commit, and create a pull request.

The editor tracks the following as pending changes:

- Content edits in pages
- New or deleted pages
- Navigation structure changes
- Media uploads
- Configuration updates

## What happens when you publish

The actions available when you click the publish button depend on your current branch and whether it has branch protection rules that require pull requests.

| Branch type | Branch protection | Available actions |
|-------------|-------------------|-------------------|
| <Tooltip headline="Deployment branch" tip="The branch that publishes to your live documentation site, typically 'main'.">Deployment branch</Tooltip> | None | **Publish** directly to your live site |
| Deployment branch | Pull requests required | **Create branch** to move changes to a new branch |
| <Tooltip headline="Feature branch" tip="An isolated branch where you work on updates before merging to your deployment branch.">Feature branch</Tooltip> | None | **Save in branch**, **Create pull request** |
| Feature branch | Pull requests required | **Save in branch**, **Create pull request** |

- **Publish**: Commits and deploys your changes to your live site immediately.
- **Save in branch**: Commits your changes to the feature branch without merging to your deployment branch.
- **Create branch**: Moves your pending changes to a new feature branch when you're on a protected deployment branch.
- **Create pull request**: Opens a pull request targeting your deployment branch.

If there are no pending changes, the publish and save actions are disabled.

Check warning on line 41 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L41

In general, use active voice instead of passive voice ('are disabled').

<Note>
Your live site updates after Mintlify builds and deploys your changes. This typically takes 30 seconds to a few minutes. Check the deployment status on your [dashboard](https://dashboard.mintlify.com).
</Note>

## When to use a branch

**Edit directly on your deployment branch** if you do not use a Git-based workflow.

**Create a branch** when you use a docs-as-code workflow where each change to your content is made on a separate branch.

Check warning on line 51 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L51

In general, use active voice instead of passive voice ('is made').

## Create and switch branches

### Create a branch

1. Click the branch name in the editor toolbar.
1. Click **Create new branch**.
1. If you have pending changes, choose whether to bring them to the new branch or leave them on the current branch.
1. Enter a name and click **Create branch**.

<Tip>
Use descriptive branch names so you can easily identify them and other people understand what each branch is for.
</Tip>

### Switch branches

1. Click the branch name in the toolbar.
1. Search for or scroll to the branch you want.
1. Click the branch to switch to it.

<Note>
Switching branches while you have unpublished changes will prompt you to bring those changes to the new branch or leave them behind. Changes left behind remain on your original branch.

Check warning on line 73 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L73

Avoid using 'will'.
</Note>

## Preview your changes

Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render exactly as they look when published.

### Access and share a preview

1. Click **Publish** in the editor toolbar.
1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`.
<Frame>
<img src="/images/editor/preview-url-light.png" alt="Preview URL emphasized in the publish menu." className="block dark:hidden" />
<img src="/images/editor/preview-url-dark.png" alt="Preview URL emphasized in the publish menu." className="hidden dark:block" />
</Frame>

Copy the URL and send it to reviewers. The preview updates automatically each time you save to the branch.

### Restrict access to previews

Preview URLs are publicly accessible by default. To restrict access to members of your Mintlify organization, enable preview authentication in the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.

### Share editor links

To invite a teammate to a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session.

The URL format is:

```text
https://dashboard.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
```

For example: `https://dashboard.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`

## Review and merge pull requests

When a pull request is open for the current branch, the publish menu shows its review status:

- **Approved**: The pull request has been approved and is ready to merge.

Check warning on line 111 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L111

In general, use active voice instead of passive voice ('been approved').
- **Changes requested**: A reviewer has requested changes before the pull request can merge.
- **Awaiting review**: The pull request is waiting for a reviewer.

Click **View request** to open the pull request in your Git provider.

When the pull request is approved, click **Merge and publish** to merge and deploy directly from the editor. The editor switches to your deployment branch after merging.

Check warning on line 117 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L117

In general, use active voice instead of passive voice ('is approved').

<Tip>
Configure branch protection rules in your Git provider to require pull requests. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) in the GitHub docs or [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/) in the GitLab docs.
</Tip>

### Review changes before merging

Click any changed file in the publish menu to open it in diff view and compare your branch against the published version. Files that can't display a diff, such as images or deleted files, appear in the list but aren't clickable.

### Simultaneous publishing

Only one publish can happen at a time per branch. If another team member publishes to the same branch, wait for the current publish to complete before trying again.

### Commit messages

When you publish, you can enter a commit message before confirming. If you leave it blank, the editor generates a message based on the files changed.

## Resolve conflicts

Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, when you and a teammate edited the same lines in a file or moved a file to different locations.

The editor displays a warning when conflicts block publishing. Follow the prompts to choose which version of each conflicting section to keep.

## Collaborate in real time

When multiple people open the same page on the same branch, they edit together in real time. Each person's cursor and edits are visible to everyone, with avatars shown in the toolbar.

Check warning on line 143 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L143

Use 'Cursor' instead of 'cursor'.

- Changes from all collaborators merge automatically. Two people editing the same section won't create conflicts.
- Undo only affects your own edits.
- If you lose your connection, edits save locally and sync when you reconnect.

When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the editor like any other collaborator. You see the agent's avatar in the toolbar and a live cursor at its most recent edit location. The cursor clears automatically after the agent finishes.

Check warning on line 149 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L149

Use 'Cursor' instead of 'cursor'.

Check warning on line 149 in editor/branching-and-publishing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/branching-and-publishing.mdx#L149

Use 'Cursor' instead of 'cursor'.

## Git sync

When someone pushes changes to your repository from outside the editor, the editor incorporates those changes automatically.

Non-overlapping changes apply automatically. If a remote change and your local edit affect the same part of a page, the editor highlights the conflict so you can resolve it.

## Commit signing

Sign commits with your GitHub account by authorizing it in your [account settings](https://dashboard.mintlify.com/settings/account). Without authorization, the Mintlify GitHub App signs commits made in the web editor.

## Git operations reference

For reference, here is how editor actions map to underlying Git operations.

| Action in the editor | Git operation |
|---|---|
| Edit a page | Changes auto-save to Mintlify servers. No Git commit yet. |
| Publish on your deployment branch | `git commit` and `git push`. Triggers a deployment. |
| Save in branch | `git commit` to the current feature branch. |
| Create pull request | `git push` and opens a pull request against your deployment branch. |
| Merge and publish | Merges the pull request and triggers a deployment. |
| Create a branch | `git checkout -b <branch-name>` |
| Switch branches | `git checkout <branch-name>` |
| External push or CLI update | Incoming changes sync into the editor automatically using a three-way merge. |

Loading
Loading