The web editor autosaves everything as you type, but your changes are only live when you choose to publish them. What happens when you publish depends on two things: which branch you’re on and whether that branch requires pull requests.Documentation Index
Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Saving versus publishing
Saving happens automatically. Your edits are stored on Mintlify’s servers and persist across browser tabs, devices, and network interruptions. 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 |
|---|---|---|
| None | Publish directly to your live site | |
| Deployment branch | Pull requests required | Create branch to move changes to a new branch |
| 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.
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.
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.Create and switch branches
Create a branch
- Click the branch name in the editor toolbar.
- Click Create new branch.
- If you have pending changes, choose whether to bring them to the new branch or leave them on the current branch.
- Enter a name and click Create branch.
Switch branches
- Click the branch name in the toolbar.
- Search for or scroll to the branch you want.
- Click the branch to switch to it.
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.
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
- Click Publish in the editor toolbar.
-
In the publish menu, click the preview URL. The URL format is
organization-branch-name.mintlify.app.
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 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: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.
- Changes requested: A reviewer has requested changes before the pull request can merge.
- Awaiting review: The pull request is waiting for a reviewer.
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.- 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.
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. 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. |