diff --git a/quickstart.mdx b/quickstart.mdx
index 076b50534..49a5ad3b9 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,251 +1,328 @@
---
-title: "Quickstart"
-description: "Deploy your documentation in minutes"
+title: "Get started with Mintlify"
+description: "Create and deploy your documentation site in under 10 minutes with zero configuration required"
icon: "rocket"
---
-This quickstart guide shows you how to set up and deploy your documentation site in minutes.
+Transform your documentation into a beautiful, searchable site that your users will love. This guide walks you through creating your first Mintlify documentation site and making your first edit.
-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 live documentation site with your custom content
+- Two workflow options for editing and publishing
+- A custom domain (optional but recommended)
-
-**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
-
+**Ready to start?** You'll need a [Mintlify account](https://mintlify.com/start) and a GitHub account to continue.
-## Getting started
+## Create your documentation site
-After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
+After creating your Mintlify account, you'll automatically get a starter documentation site deployed to a unique URL:
```
-https://.mintlify.app
+https://spearmint-docs.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
+
+Your site is live immediately! Find your exact URL in your [dashboard overview](https://dashboard.mintlify.com/).
+
-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.
+## Connect your GitHub repository
+
+Mintlify automatically creates a GitHub repository with your starter documentation. To enable automatic deployments when you make changes:
+
+
+
+ Navigate to **Settings** → **GitHub App** in your dashboard, then select **Install GitHub App**.
+
+
+ The GitHub App installation page opens in a new tab with pre-selected repositories.
+
+
+
+
+ Select your organization and choose which repositories the app can access. For most users, selecting "Selected repositories" and choosing your documentation repository is sufficient.
+
+
+
+
+
+
+
+
+ Return to your dashboard and navigate to **Settings** → **My Profile**, then select **Authorize GitHub account**.
+
+
+ Organization owners may need to approve third-party app access depending on your GitHub organization settings.
+
+
+
+
+## Choose your editing workflow
+
+Mintlify supports two distinct workflows for creating and maintaining documentation. Choose the one that fits your team's preferences:
+
+
+
+ Edit with your favorite code editor, preview locally, and deploy via Git. Perfect for technical teams who want documentation alongside code.
-
- For users who prefer a visual interface in their web browser. Click to jump to this section.
+
+ Edit directly in your browser with a visual interface. Ideal for non-technical team members or quick updates.
+
-## 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 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:
+The code-based workflow integrates seamlessly with your existing development tools and Git workflow.
-
- ```bash npm
- npm i -g mint
+
+
+ Clone the repository that Mintlify created during onboarding:
+
+ ```bash
+ git clone https://github.com/your-username/mintlify-docs.git
+ cd mintlify-docs
```
-
- ```bash pnpm
- pnpm add -g mint
+
+
+ You should see files like `docs.json`, `index.mdx`, and other starter content.
+
+
+
+
+ Install the CLI to preview changes locally:
+
+
+ ```bash npm
+ npm install -g mint
+ ```
+
+ ```bash pnpm
+ pnpm add -g mint
+ ```
+
+ ```bash yarn
+ yarn global add mint
+ ```
+
+
+
+ Requires Node.js v18 or higher. Run `node --version` to check your current version.
+
+
+
+
+ Open `index.mdx` and update the title in the frontmatter:
+
+ ```mdx index.mdx {2}
+ ---
+ title: "Welcome to Mintlify Documentation"
+ description: "Everything you need to know about our platform"
+ ---
```
-
-
-
- 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"`.
-
-```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`.
+
+ Add some content below the frontmatter:
+
+ ```mdx index.mdx
+ # Getting started
+
+ This documentation will help you understand and implement our platform quickly.
+
+
+ Get up and running in minutes with our step-by-step guide.
+
+ ```
+
-
- Optionally, skip the web editor workflow and jump to adding a custom domain.
-
+
+ Start the local development server:
+
+ ```bash
+ mint dev
+ ```
+
+
+ Your documentation site opens at `http://localhost:3000` with live reload enabled.
+
+
+
+
+
+
+
+
+
+ When you're satisfied with your changes, commit and push to deploy:
+
+ ```bash
+ git add .
+ git commit -m "Update homepage content"
+ git push origin main
+ ```
+
+
+ Mintlify automatically detects changes and deploys within 2-3 minutes. Monitor progress in your [dashboard](https://dashboard.mintlify.com) or GitHub Actions.
+
+
+
## 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".
-
-
- 
- 
-
-
-
- The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools.
-
-
-### 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.
-
+The web editor provides a visual, browser-based editing experience with instant publishing capabilities.
+
+
+
+ In your [dashboard](https://dashboard.mintlify.com), select **Editor** from the sidebar.
+
+
+ First-time users will be prompted to install the GitHub App if not already configured.
+
+
+
+
+
+
+
+
+
+ Select `index.mdx` from the file explorer, then update the content using the visual editor:
+
+ 1. Click on the title field and change it to "Welcome to Mintlify Documentation"
+ 2. Use the formatting toolbar or type `/` to insert components
+ 3. Add a card component by typing `/card` and selecting from the menu
+
+
+
+
+
+
+
+ Press ⌘ + K (Mac) or Ctrl + K (Windows) to open the command palette for quick access to all features.
+
+
+
+
+ When ready, select **Publish** in the top-right corner. Your changes deploy immediately to your live site.
+
+
+ Use **Create Branch** to preview changes via pull request before publishing to your main site.
+
+
+
+ Your updated content appears on your live site within 30 seconds.
+
+
+
+
+## Add a custom domain
+
+Replace your temporary `mintlify.app` subdomain with a professional custom domain for production use.
+
+
+
+ Navigate to [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) in your dashboard and enter your desired subdomain:
+
+ ```
+ docs.wintergreen.com
+ ```
+
+
+
+
+
+
+
+
+ Add this CNAME record with your domain provider:
+
+ | Record Type | Name | Value | TTL |
+ |-------------|------|-------|-----|
+ | CNAME | docs | cname.mintlify.app | 3600 |
+
+
+ DNS propagation typically takes 15 minutes to 4 hours, though it can take up to 48 hours in rare cases.
+
+
+
+
+ Once DNS propagates, your documentation will be available at your custom domain with automatic HTTPS.
+
+
+ Use [DNSChecker](https://dnschecker.org) to verify your CNAME record is propagated globally.
+
+
+
## 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.
-
-
- Learn how to customize colors, fonts, and the overall appearance of your documentation site.
+
+
+ Configure colors, fonts, and styling to match your brand identity.
-
- Structure your documentation with intuitive navigation to help users find what they need.
+
+
+ Organize your documentation with intuitive navigation and page hierarchy.
-
- Enhance your documentation with interactive components like accordions, tabs, and code samples.
+
+
+ Enhance content with interactive elements like tabs, accordions, and code blocks.
-
- Create interactive API references with OpenAPI and AsyncAPI specifications.
+
+
+ Generate interactive API references from OpenAPI specifications.
+
## Troubleshooting
-If you encounter issues during the setup process, check these common troubleshooting 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.
-
+
+**Problem**: `mint dev` command fails or doesn't open localhost:3000
+
+**Solutions**:
+- Verify Node.js v18+ is installed: `node --version`
+- Ensure you're in the directory containing `docs.json`
+- Check if port 3000 is already in use: `lsof -i :3000`
+- Try clearing npm cache: `npm cache clean --force`
+
+
+
+**Problem**: Pushed changes don't reflect on your documentation site
+
+**Solutions**:
+- Check [GitHub Actions](https://github.com/your-username/your-repo/actions) for build errors
+- Verify the GitHub App has access to your repository
+- Monitor deployment status in your Mintlify dashboard
+- Allow up to 5 minutes for deployment completion
+
+
+
+**Problem**: Custom domain shows errors or doesn't load your site
+
+**Solutions**:
+- Verify CNAME record points to `cname.mintlify.app`
+- Check DNS propagation with [DNSChecker](https://dnschecker.org)
+- Ensure you're using a subdomain (docs.example.com) not root domain (example.com)
+- Contact support if issues persist after 48 hours
+
+
+
+**Problem**: Unable to edit or publish through web editor
+
+**Solutions**:
+- Reinstall GitHub App from dashboard settings
+- Check organization permissions if using organization repository
+- Verify you have write access to the connected repository
+- Ensure repository isn't private if using free plan
+
+
+
+**Need additional help?** Join our [Discord community](https://mintlify.com/discord) or check our [documentation](/getting-started/overview) for comprehensive guides.
+
\ No newline at end of file