Skip to main content
Understanding Git conceptually is one thing. Knowing what to do when you sit down to update your docs is another. This lesson walks through the complete workflow from start to finish, using both the web editor and the CLI.

​
Two ways to work

Mintlify gives you two ways to edit your documentation, and they both use Git under the hood. The web editor abstracts Git almost entirely. You open a page, make changes, and publish. Mintlify handles branching and committing behind the scenes. It’s great for quick edits and for teammates who’d rather not touch a terminal. Local editing with the CLI gives you full control: a real text editor, local preview, and direct access to Git. It’s the better choice for larger restructuring work, adding new pages, or anyone who prefers their own environment. Most documentation teams end up using both, depending on the task.

​
The web editor workflow

1

Open a page in the editor

Navigate to your documentation site and click the Edit button, or go directly to dashboard.mintlify.com and open the editor from there.
2

Make your changes

Edit the page content using the visual editor or switch to markdown mode for direct MDX editing. Changes are saved automatically as you work.
3

Publish

Click Publish. Mintlify creates a branch, commits your changes, and opens a pull request — all in one step. You’ll see a preview link in the PR so you can verify the changes before merging.
4

Merge

Review the preview, then merge the pull request. Your changes go live.

​
The local CLI workflow

1

Pull the latest changes

Before starting any new work, make sure your local copy is up to date:
git pull origin main
2

Create a branch

Give your branch a name that describes the work:
git checkout -b update-authentication-guide
3

Start the local preview

Run Mintlify’s development server to see your changes in real time:
mintlify dev
Your docs site is now running locally at http://localhost:3000. Every change you save appears immediately.
4

Make your changes

Edit MDX files in your text editor. The local preview updates as you save.
5

Commit your changes

When you’re ready to save a snapshot:
git add .
git commit -m "Update authentication guide with new token format"
Commit as often as makes sense — each commit should represent a coherent unit of work.
6

Push and open a pull request

Send your branch to GitHub:
git push origin update-authentication-guide
GitHub will show a prompt to open a pull request. Click it, add a description of what you changed and why, and submit.
7

Review the preview and merge

Mintlify automatically generates a preview deployment for your PR. Share the link with anyone who needs to review the changes. Once approved, merge the PR and your changes go live.

​
What Mintlify does when you open a PR

When a pull request is opened against your documentation repository, Mintlify’s GitHub app does two things automatically:
  • Runs checks: Mintlify validates your changes — checking for broken links, missing metadata, and other issues — and reports the results directly in the PR.
  • Generates a preview: A full preview of your documentation site with the PR’s changes applied is deployed and linked in the PR. Anyone with the link can review the exact published result before a single change goes live.
This is the quality gate that makes the docs-as-code workflow worth it. Changes get reviewed in context, not just as a diff in a code review tool. Next up: Best practices for branches — when to create a branch, how to name it, and the full lifecycle from first edit to merged change.