diff --git a/quickstart.mdx b/quickstart.mdx
index 076b50534..69153abea 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,251 +1,377 @@
---
-title: "Quickstart"
-description: "Deploy your documentation in minutes"
+title: "Get started with Mintlify"
+description: "Deploy your first documentation site in under 10 minutes with our complete setup guide"
icon: "rocket"
---
-This quickstart guide shows you how to set up and deploy your documentation site in minutes.
+Transform your documentation from concept to live site in minutes. This guide walks you through account setup, choosing your workflow, and publishing your first changes.
-After completing this guide, you will have a live documentation site ready to customize and expand.
+By the end of this guide, you'll have a fully functional documentation site that you can immediately share with your team or users.
-
-**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
-
+**Before you begin**: You'll need a GitHub account to connect your repository. [Create a Mintlify account](https://mintlify.com/start) to get started.
-## Getting started
-
-After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
-
-```
-https://.mintlify.app
-```
-
-Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/).
-
-
- 
- 
-
-
-Your site's URL is available immediately. Use this URL for testing and sharing with your team while you are setting up your docs site.
-
-### Install the GitHub App
-
-Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
-
-Install the GitHub App by following the instructions from the onboarding checklist or your dashboard.
-
-1. Navigate to **Settings** in your Mintlify dashboard.
-2. Select **GitHub App** from the sidebar.
-3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page.
-4. Select the organization or user account where you want to install the app.
-5. Select the repositories that you want to connect.
-
-
- 
- 
-
-
-
- Update the GitHub App permissions if you move your documentation to a different repository.
-
-
-### Authorize your GitHub account
-
-1. Navigate to **Settings** in your Mintlify dashboard.
-2. Select **My Profile** from the sidebar.
-3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page.
-
-
- An admin for your GitHub organization may need to authorize your account depending on your organization settings.
-
-
-## Editing workflows
-
-Mintlify offers two workflows for creating and maintaining your documentation:
-
-
- For users who prefer working with existing tools in their local environment. Click to jump to this section.
+## Set up your account
+
+
+
+ Visit [mintlify.com/start](https://mintlify.com/start) and sign up with your GitHub account.
+
+ During onboarding, you'll create a new repository or connect an existing one.
+
+
+ After completing onboarding, your documentation site automatically deploys to a unique URL: `https://your-project-name.mintlify.app`
+
+
+
+
+ Navigate to your [dashboard](https://dashboard.mintlify.com) and locate your site URL on the Overview page.
+
+
+
+
+
+
+
+ Your site is live immediately and ready for testing. Bookmark this URL to share with your team during development.
+
+
+
+
+ The GitHub App enables automatic deployments when you push changes to your repository.
+
+ 1. Navigate to **Settings** → **GitHub App** in your dashboard
+ 2. Click **Install GitHub App** to open the GitHub installation page
+ 3. Select your organization or personal account
+ 4. Choose which repositories to connect (you can always add more later)
+
+
+
+
+
+
+
+ The GitHub App is now connected and will automatically deploy your documentation when you push changes.
+
+
+
+
+ Complete the GitHub authorization to enable full functionality.
+
+ 1. Go to **Settings** → **My Profile** in your dashboard
+ 2. Click **Authorize GitHub account**
+ 3. Complete the GitHub authorization flow
+
+
+ Organization admins may need to approve your authorization depending on your GitHub organization settings.
+
+
+
+ Your account is fully connected and ready to edit documentation.
+
+
+
+
+## Choose your editing workflow
+
+Mintlify supports two workflows for creating and maintaining documentation. Choose the one that best fits your team's preferences:
+
+
+
+ Work with your favorite editor and Git workflow. Perfect for developers who want to manage docs alongside code.
-
- For users who prefer a visual interface in their web browser. Click to jump to this section.
+
+ Visual browser-based editing with instant preview. Great for writers and teams who prefer a WYSIWYG experience.
+
-## Code-based workflow
-
-The code-based workflow integrates with your existing development environment and Git repositories. This workflow is best for technical teams who want to manage documentation alongside code.
+---
-### Install the CLI
+## Code-based workflow
-To work locally with your documentation, install the Command Line Interface (CLI), called [mint](https://www.npmjs.com/package/mint), by running this command in your terminal:
+Integrate documentation into your existing development environment with local editing and Git-based publishing.
-
+
+
+ Install the Mintlify CLI to preview changes locally before publishing.
+
+
```bash npm
- npm i -g mint
+ npm install -g mint
```
-
- ```bash pnpm
+
+ ```bash pnpm
pnpm add -g mint
```
-
-
-
- You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
-
-
-### Edit the documentation
-
-After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
-
-1. Open your repository created during onboarding.
-2. Open `index.mdx` and locate the top of the file:
-
-```mdx index.mdx
----
-title: "Introduction"
-description: "This is the introduction to the documentation"
----
-```
-
-3. Update the `title` field to `"Hello World"`.
+
+ ```bash yarn
+ yarn global add mint
+ ```
+
+
+
+ Requires Node.js v19 or higher. Check your version with `node --version`.
+
+
+
+ Verify installation by running `mint --version` in your terminal.
+
+
+
+
+ Get your documentation repository on your local machine.
+
+ ```bash
+ git clone https://github.com/your-username/your-docs-repo.git
+ cd your-docs-repo
+ ```
+
+
+ Your repository contains a `docs.json` configuration file and sample MDX pages.
+
+
+
+
+ Let's update the homepage to verify everything works correctly.
+
+ Open `index.mdx` in your favorite editor and update the frontmatter:
+
+ ```mdx index.mdx
+ ---
+ title: "Welcome to our docs"
+ description: "Your gateway to everything you need to know"
+ ---
+
+ # Hello World
+
+ This is your first documentation page. You can edit this content and see changes immediately.
+ ```
+
+
+ Use descriptive titles and descriptions—they improve SEO and help users understand your content.
+
+
+
+
+ Start the development server to see your changes in real-time.
+
+ ```bash
+ mint dev
+ ```
+
+ Open [localhost:3000](http://localhost:3000) in your browser to preview your site.
+
+
+ 
+ 
+
+
+
+ Your changes appear instantly in the browser. The development server automatically reloads when you save files.
+
+
+
+
+ When you're ready to go live, commit and push your changes.
+
+ ```bash
+ git add .
+ git commit -m "Update homepage content"
+ git push origin main
+ ```
+
+
+ Within 2-3 minutes, your changes will be live at `your-project-name.mintlify.app`. Check your dashboard for deployment status.
+
+
+
+
+
+ Continue with adding your own domain, or explore the web editor workflow below.
+
-```mdx index.mdx {2}
----
-title: "Hello World"
-description: "This is the introduction to the documentation"
---
-```
-
-### Preview the changes
-
-To preview the changes locally, run the following command:
-
-```bash
-mint dev
-```
-
-Your preview will be available at `localhost:3000`.
-
-
-
-
-
-
-### Push the changes
-
-When you are ready to publish your changes, push them to your repository.
-
-Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com).
-
-After the deployment completes, your latest update will be available at `.mintlify.app`.
-
-
- Optionally, skip the web editor workflow and jump to adding a custom domain.
-
## Web editor workflow
-The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. This workflow is best for people who want to work in their web browser without additional local development tools.
-
-### Access the web editor
-
-1. Log in to your [dashboard](https://dashboard.mintlify.com).
-2. Select **Editor** on the left sidebar.
-
-
- If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor.
-
-
-
- 
- 
-
-
-### Edit the documentation
-
-In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
-
-Find and select `index.mdx` in the file explorer.
-
-Then, in the editor, update the title field to "Hello World".
-
-
- 
- 
-
+Edit your documentation directly in your browser with a visual interface and instant publishing.
+
+
+
+ Navigate to the **Editor** section in your [dashboard](https://dashboard.mintlify.com).
+
+
+ If you haven't installed the GitHub App yet, you'll be prompted to install it when accessing the editor.
+
+
+
+
+
+
+
+
+ The editor loads your documentation files with a live preview alongside your editing area.
+
+
+
+
+ Select `index.mdx` from the file browser and update the content in the editor.
+
+
+
+
+
+
+
+ Use the command menu (type `/`) to quickly insert components like callouts, code blocks, and tables.
+
+
+
+ Changes appear instantly in the preview panel, so you can see exactly how your content will look.
+
+
+
+
+ Click the **Publish** button in the top-right corner to deploy your changes immediately.
+
+
+ Publishing directly updates your live site. Use branches for collaborative editing and review workflows.
+
+
+
+ Your changes are live within seconds. No build process or waiting required.
+
+
+
- The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools.
+For team collaboration, create branches in the web editor to preview changes before publishing. Learn more in our [web editor guide](/editor/getting-started).
-### Publish your changes
-
-When you're satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site.
-
-
- Use branches to preview and review changes through pull requests before deploying to your live site.
-
-
-For more details about using the web editor, including using branches and pull requests to collaborate and preview changes, see our [web editor documentation](/editor/getting-started).
-
-## Adding a custom domain
-
-While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation.
-
-To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
-
-
- 
- 
-
-
-Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider.
-
-
-| Record Type | Name | Value | TTL |
-|-------------|------|-------|-----|
-| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
-
-
-
- DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
-
-
-## Next steps
-
-Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
+---
-
- Configure site-wide styling, navigation, integrations, and more with the `docs.json` file.
+## Set up custom domain
+
+Replace your `mintlify.app` subdomain with your own branded domain for a professional documentation site.
+
+
+
+ Navigate to **Settings** → **Deployment** → **Custom Domain** in your dashboard.
+
+
+
+
+
+
+ Enter your desired domain (like `docs.yourcompany.com`).
+
+
+
+ Add a CNAME record with your domain provider using these values:
+
+ | Record Type | Name | Value | TTL |
+ |-------------|------|-------|-----|
+ | CNAME | docs (or your subdomain) | cname.mintlify.app | 3600 |
+
+
+ DNS propagation can take up to 48 hours, but typically completes within a few hours.
+
+
+
+
+ Use [DNSChecker](https://dnschecker.org) to verify your CNAME record is properly configured across DNS servers.
+
+
+ Once DNS propagates, your documentation will be available at your custom domain with automatic HTTPS.
+
+
+
+
+## What's next?
+
+You now have a live documentation site! Here are the most impactful next steps:
+
+
+
+ Set up navigation, branding, integrations, and global styling in your `docs.json` file.
-
- Learn how to customize colors, fonts, and the overall appearance of your documentation site.
+
+
+ Apply your brand colors, fonts, and styling to match your company's design system.
-
- Structure your documentation with intuitive navigation to help users find what they need.
+
+
+ Organize your content with clear navigation that helps users find information quickly.
-
- Enhance your documentation with interactive components like accordions, tabs, and code samples.
+
+
+ Enhance pages with tabs, accordions, callouts, and other engaging components.
-
- Create interactive API references with OpenAPI and AsyncAPI specifications.
+
+
+ Build interactive API documentation with OpenAPI specifications and live testing.
-## Troubleshooting
+
+ Track how users interact with your documentation to improve content and structure.
+
+
-If you encounter issues during the setup process, check these common troubleshooting solutions:
+## Common issues and solutions
-
- Make sure you have Node.js v19+ installed and that you run the `mint dev` command from the directory containing your `docs.json` file.
-
-
- Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors.
-
-
- Verify that your DNS records are set up correctly and allow sufficient time for DNS propagation (up to 48 hours). You can use tools like [DNSChecker](https://dnschecker.org) to verify your CNAME record.
-
+
+**Check these common causes:**
+- Ensure Node.js v19+ is installed (`node --version`)
+- Run `mint dev` from the directory containing your `docs.json` file
+- Check that port 3000 isn't already in use
+
+If issues persist, try clearing npm cache with `npm cache clean --force` and reinstalling: `npm install -g mint`
+
+
+
+**Deployment troubleshooting:**
+- Check deployment status in your dashboard or GitHub Actions tab
+- Verify your GitHub App has access to the correct repository
+- Look for build errors in the deployment logs
+- Deployment typically takes 2-3 minutes; wait before troubleshooting
+
+**Common build errors:**
+- Invalid MDX syntax in content files
+- Missing or malformed `docs.json` configuration
+- Broken links to internal pages or images
+
+
+
+**DNS configuration checklist:**
+- Verify CNAME record points to `cname.mintlify.app`
+- Ensure TTL is set to 3600 or lower for faster propagation
+- Check record is applied to the correct subdomain (usually `docs`)
+- Use [DNSChecker](https://dnschecker.org) to verify propagation globally
+
+**If domain still isn't working:**
+- Contact your DNS provider for propagation status
+- Ensure no conflicting A records exist for the same subdomain
+- Try using a different subdomain temporarily to test configuration
+
+
+
+**Permission problems:**
+- Reinstall the GitHub App with access to your documentation repository
+- Verify you have admin access to the repository
+- Check organization settings don't block third-party applications
+- Re-authorize your GitHub account in **Settings** → **My Profile**
+
+
+
+**Editor troubleshooting:**
+- Clear browser cache and cookies for the Mintlify domain
+- Disable browser extensions that might block the editor
+- Ensure the GitHub App is installed with repository access
+- Try using an incognito/private browsing window
+
+
+Need additional help? Visit our [community forum](https://mintlify.com/community) or contact support through your dashboard.