Work with branches

Create and manage documentation branches to preview changes, collaborate with teammates, and merge updates before publishing to production.

Branches are a feature of version control that point to specific commits in your repository. Your deployment branch, usually called main, represents the content used to build your live documentation site. All other branches are independent of your live docs unless you choose to merge them into your deployment branch.

Branches let you create separate instances of your documentation to make changes, get reviews, and try new approaches before publishing. Your team can work on branches to update different parts of your documentation simultaneously without affecting what users see on your live site.

The following diagram shows an example of a branch workflow where you create a feature branch, make changes, and then merge the feature branch into the main branch.

Always work from branches when updating documentation to keep your live site stable and enable review workflows.

Branch naming conventions

Use clear, descriptive names that explain the purpose of a branch.

Use:

• fix-broken-links
• add-webhooks-guide
• reorganize-getting-started
• ticket-123-oauth-guide

Avoid:

• temp
• my-branch
• updates
• branch1

Create a branch

Using web editor

1. Click the branch name in the editor toolbar. If you don’t see it, show the branch selector.
2. Click Create new branch.
3. Enter a descriptive name.
4. If you have unsaved changes, choose whether to bring them to the new branch or leave them on your current branch.
5. Click Create branch.

Using local development

1. Create a branch from your terminal

   git checkout -b branch-name
   

   This creates the branch and switches to it in one command.

2. Push the branch to GitHub

   git push -u origin branch-name
   

   The -u flag sets up tracking so future pushes just need git push.

Save changes on a branch

Using web editor

Click the Save in branch button in the top-right of the editor toolbar. This creates a commit and pushes your work to your branch automatically.

Using local development

Stage, commit, and push your changes.

git add .
git commit -m "Describe your changes"
git push

Switch branches

Using web editor

1. Click the branch name in the editor toolbar to open the branch dropdown.
2. Search for a branch by name or scroll through the list.
3. Click the branch you want to switch to.

Each branch in the dropdown displays a pull request indicator so you can see whether the branch has an open, draft, merged, or closed pull request, or no pull request yet.

Before you search, the dropdown lists branches created in the editor and branches with an open pull request targeting your deployment branch. Searching by name also matches other branches in your repository, including branches pushed directly through Git and branches with merged or closed pull requests. See Branch missing from the web editor branch list.

Unsaved changes are lost when switching branches. Save your work first.

Using local development

Switch to an existing branch:

git checkout branch-name

Or create and switch in one command:

git checkout -b new-branch-name

Merge branches

Once your changes are ready to publish, merge your branch into the deployment branch.

Using the editor

If Mintlify hosts your repository, click Merge and publish to merge your branch and publish your changes.

If you connected your own Git repository:

1. Click Create pull request in the top-right of the editor toolbar. The editor opens a pull request that targets your deployment branch.
2. In your Git provider, mark the pull request ready for review if it is a draft. Complete any required reviews and checks, then merge it.

See Publishing your changes for how the available publish actions change based on your branch and branch protections.

Using local development

Push your branch, then open a pull request in your Git provider that targets your deployment branch. After the pull request merges, Mintlify builds and deploys your changes to your live site.

Delete a branch

Delete branches you no longer need to keep the branch dropdown manageable.

Using web editor

1. Click the branch name in the editor toolbar to open the branch dropdown.
2. Hover over the branch that you want to delete.
3. Click the Delete branch trash icon.
4. Click Delete branch to confirm.

Deleting a branch closes any open pull request for the branch and deletes the branch from your repository. You cannot delete your deployment branch.

Using local development

Delete the branch locally:

git branch -d branch-name

Then delete it from your remote repository:

git push origin --delete branch-name