Skip to main content
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. Mintlify can also publish directly from an unprotected deployment branch, so match the steps to your team’s branch rules.

​
Work in the web editor

1

Create a feature branch

Open the branch menu in the editor toolbar and select Create new branch. Give the branch a name that describes the change, such as update-auth-guide.Creating the branch first keeps your edits separate from the deployed version.
2

Make and review your changes

Edit the page in visual or Markdown mode. The editor saves your work automatically.Use the live preview as you write. Before publishing, open the changed-file list in the publish menu and review the diff for anything you didn’t intend to change.
3

Save the branch and create a pull request

Click Publish, save the changes to your feature branch, and select Create pull request. Add a short title and explain what changed and why.The available publish actions depend on the current branch and its protection rules. If you’re on an unprotected deployment branch, Mintlify may also offer to publish directly.
4

Review and merge

Check the preview deployment and ask for any review your team requires. When the pull request is ready, merge it into the deployment branch to publish the change.

​
Work locally

1

Update the deployment branch

Switch to the branch your site deploys from, then update it. This example uses main:
Switching first matters. Running a pull command on another branch can bring changes into the wrong place.
2

Create a feature branch

Create the branch from the updated deployment branch:
3

Preview and edit

From the directory containing docs.json, start the local preview:
Edit your MDX files and check the rendered result as you work.
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.
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.

​
Respond to review feedback

Keep using the same branch and pull request. Make the requested edit, review it, and push another commit:
GitHub adds the commit to the open pull request, and Mintlify updates its preview. You don’t need to start the workflow again.

​
What Mintlify adds to the pull request

With the GitHub app connected, Mintlify generates a preview deployment for the proposed branch. The preview shows the rendered site, including navigation and components that are difficult to judge from a text diff. Your team may also enable CI checks for broken links or prose style. These checks are configurable and may depend on your Mintlify plan; they aren’t a replacement for reading the changed page. Next up: Best practices for branches — keep each branch focused enough to review and merge confidently.