The web editor and a local editor lead to the same place: a branch with a focused change, a pull request for review, and a merge into your deployment branch.
This lesson follows that review-based workflow. If your deployment branch isn’t protected, you can also publish straight from it, so match the steps to your team’s branch rules.
Work in the web editor
The editor handles the Git steps for you: it creates the branch, commits as you type, and opens the pull request.1
Create a branch
Click the branch name in the editor toolbar. Your deployment branch has a Live badge. Type a title that describes the change, such as “Update authentication guide,” then click New branch.If you don’t see a branch name in the toolbar, open More options in the top bar and turn on Branches.
2
Make your changes
Edit pages in visual mode, or switch to source mode to edit the MDX directly. The editor commits your work to the branch automatically, about 15 seconds after you stop typing. The first commit opens a pull request, as a draft if your team has that setting on.Before you ask for review, look over the changed files in the pull request for anything you didn’t mean to change.
3
Request review
Click Publish, then Request review. This marks the pull request ready for review. Make sure its description explains what changed and why, so reviewers know where to focus.
4
Merge and publish
Check the preview deployment and get any review your team requires. When the pull request is approved, click Publish, then Merge and publish. The editor merges the pull request, deploys your change, and switches you back to the deployment branch.
If you don’t see a Publish button, your project has auto publish turned on. Edits commit straight to the deployment branch shortly after you stop typing, with no review step.
Work locally
1
Update the deployment branch
Switch to the branch your site deploys from, then update it. This example uses Starting from an up-to-date deployment branch means your new branch includes your teammates’ latest work, which avoids conflicts later.
main:2
Create a feature branch
Create the branch from the updated deployment branch:
3
Preview and edit
From the directory containing Edit your MDX files and check the rendered result as you work.
docs.json, start the local preview:4
Review the change
Inspect both the affected files and their exact edits:Look for temporary notes, secrets, generated files, and unrelated edits before staging anything. Then check for problems the preview might not show:
mint broken-links finds internal links that point nowhere. mint validate checks that the site builds.5
Commit the files that belong together
Stage the files you reviewed, then commit them:Add more paths when they belong to the same change. Avoid staging the whole repository by habit.
6
Push and open a pull request
Push the new branch and set its upstream connection:Follow GitHub’s link or open the repository to create a pull request. Explain the purpose of the change and point reviewers to anything that needs special attention.
7
Check the preview and merge
Open the Mintlify preview from the pull request. After the change passes your team’s review and checks, merge it into the deployment branch.