From 383969ed9fe5e2d5aced1607498656a464409b99 Mon Sep 17 00:00:00 2001
From: "mintlify-development[bot]"
<109878554+mintlify-development[bot]@users.noreply.github.com>
Date: Wed, 17 Sep 2025 02:23:22 +0000
Subject: [PATCH] Update quickstart.mdx
---
quickstart.mdx | 187 +++++++++++++++++++++++++------------------------
1 file changed, 97 insertions(+), 90 deletions(-)
diff --git a/quickstart.mdx b/quickstart.mdx
index 076b50534..9864805ed 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,47 +1,47 @@
---
title: "Quickstart"
-description: "Deploy your documentation in minutes"
+description: "Build beautiful documentation in under 10 minutes"
icon: "rocket"
---
-This quickstart guide shows you how to set up and deploy your documentation site in minutes.
+Get your documentation site live in minutes with this step-by-step guide.
-After completing this guide, you will have a live documentation site ready to customize and expand.
+You'll go from zero to a fully deployed documentation site that's ready for your team to use and customize.
-**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
+**Before you start**: [Sign up for Mintlify](https://mintlify.com/start) and complete the initial setup wizard.
-## Getting started
+## Launch your site
-After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
+Once you finish the setup wizard, your documentation automatically goes live at:
```
https://.mintlify.app
```
-Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/).
+You can find this URL in your [dashboard](https://dashboard.mintlify.com/) overview section.
-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.
+Your site is live immediately - share this URL with your team while you build out your content.
-### Install the GitHub App
+### Connect GitHub
-Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
+Set up automatic deployments by connecting your GitHub repository.
-Install the GitHub App by following the instructions from the onboarding checklist or your dashboard.
+Follow these steps to install the GitHub integration:
-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.
+1. Go to **Settings** in your dashboard
+2. Click **GitHub App** in the sidebar
+3. Click **Install GitHub App** - this opens GitHub in a new tab
+4. Choose your organization or personal account
+5. Select which repositories to connect
@@ -49,38 +49,40 @@ Install the GitHub App by following the instructions from the onboarding checkli
- Update the GitHub App permissions if you move your documentation to a different repository.
+ Need to change repositories later? Update the GitHub App permissions anytime.
-### Authorize your GitHub account
+### Link your GitHub profile
-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.
+Connect your personal GitHub account for seamless editing:
+
+1. Navigate to **Settings** → **My Profile**
+2. Click **Authorize GitHub account**
+3. Complete the authorization in the new GitHub tab
- An admin for your GitHub organization may need to authorize your account depending on your organization settings.
+ Your organization admin might need to approve this connection based on your GitHub settings.
-## Editing workflows
+## Choose your editing style
-Mintlify offers two workflows for creating and maintaining your documentation:
+Pick the workflow that matches how you like to work:
-
- For users who prefer working with existing tools in their local environment. Click to jump to this section.
+
+ Work locally with your favorite code editor and Git workflow.
-
- For users who prefer a visual interface in their web browser. Click to jump to this section.
+
+ Edit directly in your browser with our visual editor.
-## Code-based workflow
+## Developer 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.
+Perfect for teams who want documentation integrated with their development process.
-### Install the CLI
+### Set up the CLI
-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:
+Install our command-line tool to work with your docs locally:
```bash npm
@@ -93,15 +95,15 @@ To work locally with your documentation, install the Command Line Interface (CLI
- You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
+ Requires Node.js v19 or higher. Having trouble? Check our troubleshooting section below.
-### Edit the documentation
+### Make your first edit
-After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
+Let's update your homepage to see the workflow in action:
-1. Open your repository created during onboarding.
-2. Open `index.mdx` and locate the top of the file:
+1. Clone the repository created during setup
+2. Open `index.mdx` and find the frontmatter:
```mdx index.mdx
---
@@ -110,53 +112,59 @@ description: "This is the introduction to the documentation"
---
```
-3. Update the `title` field to `"Hello World"`.
+3. Change the title to something new:
```mdx index.mdx {2}
---
-title: "Hello World"
+title: "Welcome to our docs"
description: "This is the introduction to the documentation"
---
```
-### Preview the changes
+### Test locally
-To preview the changes locally, run the following command:
+See your changes before publishing:
```bash
mint dev
```
-Your preview will be available at `localhost:3000`.
+Open `localhost:3000` to preview your site.
-### Push the changes
+### Deploy your changes
-When you are ready to publish your changes, push them to your repository.
+Ready to go live? Just push 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).
+```bash
+git add .
+git commit -m "Update homepage title"
+git push
+```
-After the deployment completes, your latest update will be available at `.mintlify.app`.
+Mintlify detects your changes and automatically rebuilds your site. Track the deployment in your GitHub Actions or dashboard.
-
- Optionally, skip the web editor workflow and jump to adding a custom domain.
+Your updates appear at `.mintlify.app` within minutes.
+
+
+ Ready to use your own domain? Jump ahead to the custom domain section.
-## Web editor workflow
+## Browser 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.
+Edit your documentation directly in your browser - no local setup required.
-### Access the web editor
+### Open the editor
-1. Log in to your [dashboard](https://dashboard.mintlify.com).
-2. Select **Editor** on the left sidebar.
+1. Log into your [dashboard](https://dashboard.mintlify.com)
+2. Click **Editor** in the sidebar
- If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor.
+ First time? You'll be prompted to install the GitHub App if you haven't already.
@@ -164,13 +172,12 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf
-### Edit the documentation
-
-In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
+### Edit your content
-Find and select `index.mdx` in the file explorer.
+Navigate to any file in the sidebar and start editing. Let's update the homepage:
-Then, in the editor, update the title field to "Hello World".
+1. Click `index.mdx` in the file tree
+2. Change the title field to "Welcome to our docs"
@@ -178,74 +185,74 @@ 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.
+ Press / anywhere in the editor to open the command palette and access formatting tools.
-### Publish your changes
+### Go live
-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.
+Click **Publish** in the top-right corner. Your changes deploy instantly to your live site.
- Use branches to preview and review changes through pull requests before deploying to your live site.
+ Use branches for team collaboration and review changes before they go live.
-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).
+Learn more about advanced editor features in our [web editor guide](/editor/getting-started).
-## Adding a custom domain
+## Custom domain
-While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation.
+Ready to use your own domain instead of the Mintlify subdomain?
-To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
+Head to [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) in your dashboard.
-Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider.
+Enter your domain (like `docs.yourcompany.com`) and configure these DNS settings with your domain provider:
| Record Type | Name | Value | TTL |
|-------------|------|-------|-----|
-| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
+| CNAME | docs (or your subdomain) | cname.mintlify.app | 3600 |
- DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
+ DNS changes typically take 15-30 minutes but can take up to 48 hours in some cases.
-## Next steps
+## What's next?
-Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
+Your documentation site is live! Here's how to make it even better:
-
- Configure site-wide styling, navigation, integrations, and more with the `docs.json` file.
+
+ Configure colors, navigation, integrations, and more in your `docs.json` file.
-
- Learn how to customize colors, fonts, and the overall appearance of your documentation site.
+
+ Match your brand with custom colors, fonts, and styling options.
-
- Structure your documentation with intuitive navigation to help users find what they need.
+
+ Organize pages with groups, tabs, and hierarchical navigation.
-
- Enhance your documentation with interactive components like accordions, tabs, and code samples.
+
+ Use callouts, code blocks, tabs, and other interactive elements.
-
- Create interactive API references with OpenAPI and AsyncAPI specifications.
+
+ Generate interactive API references from OpenAPI specifications.
-## Troubleshooting
+## Common issues
-If you encounter issues during the setup process, check these common troubleshooting solutions:
+Running into problems? Here are quick fixes for the most common issues:
-
- Make sure you have Node.js v19+ installed and that you run the `mint dev` command from the directory containing your `docs.json` file.
+
+ Check that you have Node.js v19+ installed and you're running the command from the folder 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.
+
+ Deployments can take 2-3 minutes. Check your GitHub Actions tab or dashboard deployment logs for any 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.
+
+ Double-check your DNS records and wait for propagation. Use [DNSChecker](https://dnschecker.org) to verify your CNAME record is set up correctly.