diff --git a/quickstart.mdx b/quickstart.mdx
index 2d9357557..e7d791371 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,28 +1,32 @@
---
title: "Quickstart"
description: "Get started with Mintlify by deploying your documentation site in minutes and making your first content change with the web editor or Git."
-keywords: ["quickstart","deploy","get started","first steps","tutorial","setup","onboarding"]
+keywords: ["quickstart", "deploy", "get started", "first steps", "tutorial", "setup", "onboarding"]
---
-After you complete this guide, you'll have a live documentation site ready to customize and update.
+By the end of this guide, you'll have a live documentation site deployed and your first content change published.
-## Before you begin
+## How Mintlify works
-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.
+Mintlify uses a docs-as-code approach. Every page on your site is a file — usually MDX — stored in a Git repository. When you push a change to that repository, Mintlify automatically rebuilds and deploys your site.
-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.
+You can edit documentation two ways:
-
- Using an AI coding tool?
-
- Copy the following prompt to add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your documentation.
-
+
+
+ Edit in your browser — no local setup required. Changes publish directly to Git.
+
-
+ Clone your repo, preview locally with `mint dev`, and push to deploy.
+
+
-npx skills add https://mintlify.com/docs
+
+ **Using an AI coding tool?** Add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your docs.
+
-Then add the Mintlify MCP server for access to documentation search. Follow the setup instructions at https://www.mintlify.com/docs/ai/model-context-protocol.md" actions={["copy", "cursor"]}>
+
Install the Mintlify skill to get context on Mintlify project structure, components, and documentation best practices:
npx skills add https://mintlify.com/docs
@@ -32,45 +36,76 @@ Then add the Mintlify MCP server for access to documentation search. Follow the
## Deploy your documentation site
-Go to [mintlify.com/start](https://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.app` URL.
-
-
-
- If you want to get started quickly without connecting your own repository, you can skip the Git provider connection during onboarding. Mintlify creates a private repository in a private organization and automatically configures the GitHub App for you.
-
- This lets you use the web editor immediately. If you want to use your own repository later, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard to migrate your content using the Git setup wizard. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository) for details.
-
-
-
-## View your deployed site
-
-Your documentation site is now deployed at `https://.mintlify.app`.
-
-Find your exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/).
-
-
- 
-
- 
-
-
-
- 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](/customize/custom-domain).
-
+
+
+ Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding flow. You'll connect your GitHub account, select or create a repository, and install the GitHub App.
+
+
+
+ During onboarding, you can skip the GitHub step. Mintlify will create a private repository under a managed organization and configure everything automatically — you can start using the web editor immediately.
+
+ When you're ready to move to your own repo, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard and use the Git setup wizard. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository) for details.
+
+
+
+
+ After onboarding, your site deploys to `https://.mintlify.app`.
+
+ Find the exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/).
+
+
+
+
+
+
+
+ This URL is live immediately. Share it with your team for testing. When you're ready to go public, [add a custom domain](/customize/custom-domain).
+
+
+
## Make your first change
+Choose your preferred workflow:
+
+
+
+
+ Go to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard.
+
+
+ Open the **Introduction** page and update the description field.
+
+
+ 
+ 
+
+
+
+ Click **Publish** in the top-right of the editor toolbar. The editor commits your change to Git and triggers a deployment.
+
+
+ On the [Overview](https://dashboard.mintlify.com/) page of your dashboard, watch the deployment status. Refresh your documentation site once it finishes to see your change live.
+
+
+
@@ -82,20 +117,19 @@ Find your exact URL on the **Overview** page of your [dashboard](https://dashboa
npm i -g mint
```
-
```bash pnpm
pnpm add -g mint
```
- See [Install the CLI](/cli/install) for full details and troubleshooting.
+ See [Install the CLI](/cli/install) for troubleshooting and full details.
- If you haven't already cloned your repository locally, follow the instructions in [Clone your repository](/cli/install#clone-your-repository).
+ If you haven't cloned your docs repo locally yet, follow the steps in [Clone your repository](/cli/install#clone-your-repository).
- Open `index.mdx` in your preferred editor and update the description in the frontmatter:
+ Open `index.mdx` in your editor and change the description in the frontmatter:
```mdx
---
@@ -105,16 +139,16 @@ Find your exact URL on the **Overview** page of your [dashboard](https://dashboa
```
- Run the following command from your documentation directory:
+ From your documentation directory, run:
```bash
mint dev
```
- View your preview at `http://localhost:3000`.
+ View your changes at `http://localhost:3000` before pushing.
-
- Commit and push your changes to trigger a deployment:
+
+ Commit and push to trigger a deployment:
```bash
git add .
@@ -122,37 +156,7 @@ Find your exact URL on the **Overview** page of your [dashboard](https://dashboa
git push
```
- Mintlify automatically deploys your changes. View your deployment status on the [Overview](https://dashboard.mintlify.com/) page of your dashboard.
-
-
-
-
-
-
- Navigate to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard.
-
-
- Open the **Introduction** page and update the description.
-
-
-
-
-
-
-
-
- Click the **Publish** button in the top-right of the web editor toolbar.
-
-
- On the [Overview](https://dashboard.mintlify.com/) 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.
+ Mintlify deploys automatically. Track the status on your [dashboard Overview](https://dashboard.mintlify.com/).
@@ -160,14 +164,20 @@ Find your exact URL on the **Overview** page of your [dashboard](https://dashboa
## Next steps
-
- Edit documentation in your browser and preview how your pages look when published.
-
+
+
+ Edit, preview, and publish documentation directly in your browser.
+
+
+
+ Find broken links, check accessibility, validate OpenAPI specs, and more.
+
-
- Find broken links, check accessibility, validate OpenAPI specs, and more.
-
+
+ Swap your `.mintlify.app` URL for your own domain.
+
-
- Use your own domain for your documentation site.
-
\ No newline at end of file
+
+ Configure branding, navigation, colors, and page layouts.
+
+
\ No newline at end of file