Quickstart

Get started with Mintlify by deploying your documentation site in minutes and making your first content change with the web editor or Git.

After you complete this guide, you’ll have a live documentation site ready to customize and update.

Using an AI agent?

Copy the following prompt to have your agent set up your site for you. It directs your agent to create your account and deploy your site. It also adds the Mintlify skill and MCP server for better results when you update your content.

The prompt splits the quickstart into tasks your agent can complete and directs it to ask you for any information it needs while getting everything set up.

Copy and paste to have your agent set up your Mintlify site.

Get my documentation live on a published Mintlify site. You are successfully done when you give me the live URL and confirm it loads. Tell me clearly whenever a step needs my input—do everything else yourself. If this prompt was pasted before (for example, after a restart), continue from where things left off instead of starting over. If you don’t have terminal or command execution access, tell me to follow the manual steps at mintlify.com/start instead. Everything below requires running commands and requires Node.js v20.17.0+ (LTS versions recommended).

Ask for my existing content that will be used for my Mintlify site. This may be a local folder or a repo. Verify the source before building: echo back exactly what you’re reading and list its top-level contents so I can confirm it’s right. If you can’t access something I named (private repos return 404, same as nonexistent), stop and ask. Never substitute a different source.
Check whether mint is installed with mint --version. If it’s missing, install it with npm i -g mint (or pnpm add -g mint). If it’s already installed, run mint update instead of reinstalling.
Run mint status. If it already shows an organization, skip to step 7.
Needs me: If mint status shows I’m not logged in, ask me directly whether I already have a Mintlify account. Don’t guess.
- If I have one: run mint login. You need me for browser steps and to approve access.
- If I don’t: ask me for my first name, last name, company, and email if I haven’t given them already—never invent these. Run mint signup --firstName [firstName] --lastName [lastName] --company [company] --email [email] as a background task since it blocks until I click a verification link that can take several minutes.
Needs me: I’ll check my email and click the verification link. That opens a browser tab that automatically finishes the rest of account creation/logging in. I must approve the CLI, then connect a GitHub repository or let Mintlify host one. Tell me clearly this step is mine, then wait for it before continuing.
Run mint status again to confirm an organization and subdomain now exist. The subdomain isn’t provisioned until I select or connect a repository during the step 5 browser flow — so if mint status shows my organization but no subdomain yet, that almost always means I haven’t finished the repo step, not that anything is broken. Don’t treat it as an error or poll blindly: wait until I confirm I’ve completed onboarding, then re-run mint status. Provisioning can still lag a few seconds after that, so retry a few times before concluding something is wrong.
Needs me: ask for the URL of the repository connected to my Mintlify project — mint status doesn’t expose it, so you can’t look it up yourself. Clone it once I give it to you.
Check what’s in that repo. If I connected my own existing docs repo, my content is already there — don’t overwrite it. If Mintlify created the repo, it contains starter template content — replace that with my actual docs content from step 1. Only use mint new [directory] if I want a different theme or template than what’s in the repo — scaffold it locally, then use its output in place of the seeded content.
Preview with mint dev, which generally starts on http://localhost:3000 unless that port is in use. It blocks until stopped, so run it as a background task. Verify the preview loads, then stop it before continuing.
Commit and push your changes. Mintlify deploys automatically on push.
Needs me: If I want a custom domain, run mint add-domain <domain>. It prints the DNS records I need to add with my domain provider. Tell me the DNS records, since only I can configure them at my registrar. Make it clear that this is a step I must complete.
Confirm my site is live: fetch https://<subdomain>.mintlify.site (find the subdomain via mint status) and confirm it loads. If I added a custom domain in step 11, also fetch that domain and confirm it loads before calling this step done—DNS propagation can lag, so retry a few times before treating a failed fetch as an error.
Set yourself up to keep working here: install the Mintlify skill with npx skills add https://mintlify.com/docs, then register the admin MCP server at https://mcp.mintlify.com for your specific tool. For example, claude mcp add --transport http mintlify https://mcp.mintlify.com for Claude Code or fetch https://mintlify.com/docs/ai/mintlify-mcp.md for instructions for Claude, Cursor, Codex, or ChatGPT. Do this step yourself—don’t ask me to run these commands.
Needs me: the first admin MCP tool call opens a browser window for OAuth login. Approve it there. Most tools don’t load newly added MCP servers mid-session — if the Mintlify tools don’t show up, tell me to restart you and we’ll pick up from here.
If any command fails in a way not covered above, stop and tell me the exact error rather than guessing or retrying blindly. If it looks like something’s wrong on Mintlify’s end rather than in what you’re doing, check https://status.mintlify.com or point me to https://mintlify.com/docs/contact-support.

Before you begin

Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository.

When you connect your documentation repository to your project, you can work on your documentation locally or in the web editor and sync any changes to your remote repository.

Deploy your documentation site

Go to mintlify.com/start and complete the onboarding process. During onboarding, you’ll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments.

After onboarding, your documentation site deploys and is accessible at your .mintlify.site URL.

View your deployed site

Your documentation site is now deployed at https://<your-project-name>.mintlify.site.

Find your exact URL on the Overview page of your dashboard.

Overview page of the Mintlify dashboard.

Your site is ready to view immediately. Use this URL for testing and sharing with your team. Before sharing with your users, you may want to add a custom domain.

Make your first change

Install the CLI

The CLI requires Node.js v20.17.0 or higher. Use an LTS version for stability.

npm i -g mint

See Install the CLI for full details and troubleshooting.

Clone your repository

If you haven’t already cloned your repository locally, clone it using Git:

git clone <your-repository-url>

If your repository is in Mintlify’s private organization, see Clone to your own repository to move it to your account first.

Edit a page

Open index.mdx in your preferred editor and update the description in the frontmatter:

---
title: "Introduction"
description: "Your custom description here"
---

Preview locally

Run the following command from your documentation directory:

mint dev

View your preview at http://localhost:3000.

Push your changes

Commit and push your changes to trigger a deployment:

git add .
git commit -m "Update description"
git push

Mintlify automatically deploys your changes. View your deployment status on the Overview page of your dashboard.

Open the web editor

Navigate to the web editor in your dashboard.

Edit a page

Open the Introduction page and update the description.

Introduction page open in the web editor with the description edited to say Hello world!.

Publish

Click Publish in the top-right of the web editor toolbar.

View live

On the Overview page of your dashboard, you can see your site’s deployment status. When it finishes deploying, refresh your documentation site to see your changes live.