Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

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. No terminal required and you can edit right in your browser. Local editing with the CLI lets you use whichever text editor you prefer, generate a local preview via the CLI command mint dev, and use Git however you like. Most documentation teams end up using both.

​
The web editor workflow

1

Open a page in the editor

Open the editor on dashboard.mintlify.com and select the page you want to edit.
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 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:
mint 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

Push your branch to GitHub:
git push origin update-authentication-guide
GitHub shows 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 you open a pull request against your documentation repository, Mintlify’s GitHub app does two things:
  • 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 deploys and the app links it in the PR. Anyone with the link can review the exact published result before a single change goes live.
This is the quality gate of the docs-as-code workflow. Changes get reviewed in context and can be safely previewed before publishing. 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.