Skip to main content
Mintlify connects to a GitHub repository containing your MDX files and docs.json configuration, then hosts and deploys your docs automatically. This guide walks you through cloning the starter repo, previewing your changes locally, and going live.
1

Clone the starter repo

Start with the Mintlify starter template to get a working docs.json and a set of example pages.
Go to the mintlify/starter repository on GitHub and click Use this template to create a copy under your own account. Then clone it locally:
git clone https://github.com/your-username/your-docs-repo.git
cd your-docs-repo
If you’re new to cloning repositories, see GitHub’s guide on cloning.
Install the Mintlify CLI, then start the local preview server from your docs directory:
npm i -g mint
mint dev
Your docs site opens at http://localhost:3000. The preview updates automatically as you edit your MDX files.
The CLI requires Node.js v19 or later. Run node -v to check your version.
Open docs.json in your editor and update the name and colors fields to match your brand:
{
  "name": "Your Company Docs",
  "colors": {
    "primary": "#your-primary-color",
    "light": "#your-light-color",
    "dark": "#your-dark-color"
  }
}
Save the file and the local preview will reflect your changes immediately. See Site settings for the full list of configuration options.
2

Install the GitHub App

Mintlify deploys your docs automatically whenever you push to GitHub. To enable this, install the Mintlify GitHub App from your dashboard.
  1. Sign in at dashboard.mintlify.com.
  2. Click Add new project and select your docs repository.
  3. Follow the prompts to install the Mintlify GitHub App on that repository.
Once installed, Mintlify watches for pushes to your default branch and triggers a new deployment automatically.
You can install the GitHub App on a specific repository or across your entire organization. Start with a single repository to keep permissions narrow.
3

Push your changes and go live

Commit your changes and push to GitHub. Mintlify picks up the push, builds your docs, and publishes them — usually within seconds.
git add .
git commit -m "Initial docs setup"
git push
Open your dashboard to see the deployment status. When the build succeeds, you’ll see a checks passed confirmation and a link to your live site.
Every push to the default branch triggers a new deployment. Pushes to other branches do not affect your live site.

​
Next steps

Markdown and MDX

Learn how to format text, add images, and use interactive components in your pages.

Site settings

Configure your logo, fonts, navigation, and more in docs.json.

Code blocks

Add syntax-highlighted code examples with copy buttons and line highlighting.

API reference

Auto-generate interactive API docs from an OpenAPI specification.