Skip to content

Commit 9a2530b

Browse files
mintlify-development[bot]mintlify-development[bot]
authored
Update quickstart.mdx
1 parent e29f437 commit 9a2530b

File tree

1 file changed

+84
-176
lines changed

1 file changed

+84
-176
lines changed

‎quickstart.mdx‎

Lines changed: 84 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -4,218 +4,126 @@ description: "Get your documentation site live in under 10 minutes"
44
icon: "rocket"
55
---
66

7-
Build and deploy beautiful documentation in minutes. This guide walks you through creating your first documentation site from setup to deployment.
7+
Create beautiful documentation in minutes. This guide gets you from zero to a live documentation site with automatic deployments.
88

9-
<Info>
10-
**Before you start**: You'll need a [Mintlify account](https://mintlify.com/start). The onboarding process creates your first project automatically.
11-
</Info>
12-
13-
## Your site is already live
14-
15-
Once you complete onboarding, your documentation site is automatically deployed at:
16-
17-
```
18-
https://<your-project-name>.mintlify.app
19-
```
20-
21-
You can find this URL on your [dashboard overview](https://dashboard.mintlify.com/).
22-
23-
<Frame>
24-
<img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify Domain" className="block dark:hidden" />
25-
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify Domain" className="hidden dark:block" />
26-
</Frame>
9+
## Step 1: Create your account
2710

28-
## Connect your GitHub repository
11+
Sign up at [mintlify.com/start](https://mintlify.com/start). Your first documentation site is created automatically during onboarding.
2912

30-
Link your GitHub repository to enable automatic deployments when you push changes.
13+
Your site goes live immediately at `https://<your-project-name>.mintlify.app`.
3114

32-
### Install the GitHub App
15+
## Step 2: Connect GitHub
3316

34-
1. Go to **Settings** → **GitHub App** in your dashboard
35-
2. Click **Install GitHub App**
36-
3. Select your organization and repositories
37-
4. Complete the installation
17+
Enable automatic deployments by connecting your GitHub repository.
3818

39-
<Frame>
40-
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App Installation" className="block dark:hidden" />
41-
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App Installation" className="hidden dark:block" />
42-
</Frame>
19+
<Steps>
20+
<Step title="Install GitHub App">
21+
Go to **Settings** → **GitHub App** and click **Install GitHub App**. Select your organization and repositories.
22+
</Step>
23+
<Step title="Authorize account">
24+
Navigate to **Settings** → **My Profile** and click **Authorize GitHub account**.
25+
</Step>
26+
</Steps>
4327

44-
### Authorize your account
28+
## Step 3: Start editing
4529

46-
1. Navigate to **Settings** → **My Profile**
47-
2. Click **Authorize GitHub account**
48-
3. Complete the authorization process
30+
Choose how you want to work with your documentation:
4931

50-
<Tip>
51-
Organization admins may need to approve the authorization depending on your GitHub settings.
52-
</Tip>
53-
54-
## Choose your editing workflow
55-
56-
Pick the workflow that matches how you prefer to work:
57-
58-
<CardGroup cols={2}>
59-
<Card title="Local development" icon="terminal" href="#local-development">
60-
Edit files locally with your favorite tools and Git workflow
32+
<Tabs>
33+
<Tab title="Web Editor">
34+
Edit directly in your browser - no setup required.
35+
36+
1. Open your [dashboard](https://dashboard.mintlify.com)
37+
2. Click **Editor** in the sidebar
38+
3. Select any file to start editing
39+
4. Click **Publish** to deploy changes instantly
40+
41+
<Frame>
42+
<img alt="Web editor" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
43+
<img alt="Web editor" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
44+
</Frame>
45+
</Tab>
46+
47+
<Tab title="Local Development">
48+
Work locally with your favorite tools and Git workflow.
49+
50+
**Install CLI:**
51+
```bash
52+
npm i -g mint
53+
```
54+
55+
**Edit and preview:**
56+
1. Edit any `.mdx` file in your repository
57+
2. Run `mint dev` to preview at `localhost:3000`
58+
3. Push changes to GitHub for automatic deployment
59+
60+
<Warning>
61+
Requires Node.js v19+. Check with `node --version`.
62+
</Warning>
63+
</Tab>
64+
</Tabs>
65+
66+
## Step 4: Customize your site
67+
68+
Make it yours with these quick customizations:
69+
70+
<CardGroup cols={3}>
71+
<Card title="Brand colors" icon="palette">
72+
Update `docs.json` with your brand colors and logo
73+
</Card>
74+
<Card title="Navigation" icon="bars">
75+
Organize pages into groups and sections
6176
</Card>
62-
<Card title="Web editor" icon="mouse-pointer-2" href="#web-editor">
63-
Edit directly in your browser with a visual interface
77+
<Card title="Custom domain" icon="globe">
78+
Replace `.mintlify.app` with your own domain
6479
</Card>
6580
</CardGroup>
6681

67-
## Local development
68-
69-
Work with your documentation files locally using familiar development tools.
70-
71-
### Install the CLI
72-
73-
Install the Mintlify CLI to preview changes locally:
74-
75-
<CodeGroup>
76-
```bash npm
77-
npm i -g mint
78-
```
79-
80-
```bash pnpm
81-
pnpm add -g mint
82-
```
83-
</CodeGroup>
84-
85-
<Warning>
86-
Requires Node.js v19 or higher. Check your version with `node --version`.
87-
</Warning>
88-
89-
### Make your first edit
90-
91-
Let's update your homepage:
92-
93-
1. Open `index.mdx` in your repository
94-
2. Change the title in the frontmatter:
95-
96-
```mdx index.mdx
97-
---
98-
title: "Welcome to our docs"
99-
description: "Everything you need to get started"
100-
---
101-
```
82+
### Add a custom domain
10283

103-
### Preview locally
104-
105-
Start the development server:
106-
107-
```bash
108-
mint dev
109-
```
110-
111-
Your site will be available at `http://localhost:3000`.
112-
113-
<Frame>
114-
<img src="/images/quickstart/mintlify-dev-light.png" alt="Local preview" className="block dark:hidden" />
115-
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Local preview" className="hidden dark:block" />
116-
</Frame>
117-
118-
### Deploy your changes
119-
120-
Push your changes to GitHub:
121-
122-
```bash
123-
git add .
124-
git commit -m "Update homepage title"
125-
git push
126-
```
127-
128-
Mintlify automatically builds and deploys your changes. Check the deployment status in your GitHub Actions or dashboard.
129-
130-
## Web editor
131-
132-
Edit your documentation directly in your browser without any local setup.
133-
134-
### Access the editor
135-
136-
1. Open your [dashboard](https://dashboard.mintlify.com)
137-
2. Click **Editor** in the sidebar
138-
139-
<Frame>
140-
<img alt="Web editor interface" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
141-
<img alt="Web editor interface" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
142-
</Frame>
143-
144-
### Edit your content
145-
146-
1. Select `index.mdx` from the file explorer
147-
2. Update the title field to "Welcome to our docs"
148-
3. Use the formatting toolbar or type `/` for quick commands
149-
150-
<Frame>
151-
<img alt="Editing content" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
152-
<img alt="Editing content" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
153-
</Frame>
154-
155-
### Publish instantly
156-
157-
Click **Publish** in the top-right corner to deploy your changes immediately.
158-
159-
<Tip>
160-
Use branches to preview changes before publishing to your live site. Learn more in our [web editor guide](/editor/getting-started).
161-
</Tip>
162-
163-
## Add a custom domain
164-
165-
Replace your `.mintlify.app` subdomain with your own domain.
166-
167-
1. Go to **Settings** → **Custom Domain** in your dashboard
168-
2. Enter your domain (e.g., `docs.yourcompany.com`)
84+
1. Go to **Settings** → **Custom Domain**
85+
2. Enter your domain (e.g., `docs.company.com`)
16986
3. Add this CNAME record to your DNS:
17087

171-
<Table>
172-
| Record Type | Name | Value | TTL |
173-
|-------------|------|-------|-----|
88+
| Type | Name | Value | TTL |
89+
|------|------|-------|-----|
17490
| CNAME | docs | cname.mintlify.app | 3600 |
175-
</Table>
176-
177-
<Frame>
178-
<img src="/images/quickstart/custom-domain-light.png" alt="Custom domain setup" className="block dark:hidden" />
179-
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom domain setup" className="hidden dark:block" />
180-
</Frame>
18191

18292
<Info>
183-
DNS changes typically take 5-30 minutes but can take up to 48 hours to fully propagate.
93+
DNS changes take 5-30 minutes to propagate.
18494
</Info>
18595

18696
## What's next?
18797

188-
Your documentation site is live! Here's how to make it even better:
189-
19098
<CardGroup cols={2}>
191-
<Card title="Customize your site" icon="paintbrush" href="themes">
192-
Change colors, fonts, and styling to match your brand
99+
<Card title="Write content" icon="pen" href="/writing-content/page">
100+
Learn MDX syntax and use interactive components
193101
</Card>
194-
<Card title="Organize navigation" icon="map" href="navigation">
195-
Structure your content with groups, tabs, and sections
102+
<Card title="API docs" icon="code" href="/api-playground/overview">
103+
Generate interactive API documentation
196104
</Card>
197-
<Card title="Add components" icon="puzzle" href="/components/accordions">
198-
Use interactive elements like tabs, callouts, and code blocks
105+
<Card title="Themes" icon="paintbrush" href="/themes">
106+
Customize colors, fonts, and styling
199107
</Card>
200-
<Card title="API documentation" icon="code" href="/api-playground/overview">
201-
Generate interactive API docs from OpenAPI specs
108+
<Card title="Analytics" icon="chart-line" href="/analytics/overview">
109+
Track usage and optimize your documentation
202110
</Card>
203111
</CardGroup>
204112

205-
## Need help?
113+
## Troubleshooting
206114

207115
<AccordionGroup>
208-
<Accordion title="Local preview isn't working">
209-
Ensure you have Node.js v19+ and run `mint dev` from your project root directory (where `docs.json` is located).
116+
<Accordion title="Site not updating after pushing changes">
117+
Check GitHub Actions for build errors. Builds typically take 1-3 minutes.
210118
</Accordion>
211119

212-
<Accordion title="Changes aren't showing on my live site">
213-
Check your GitHub Actions for build errors. Deployments typically take 1-3 minutes.
120+
<Accordion title="Local preview not working">
121+
Ensure Node.js v19+ is installed and run `mint dev` from your project root (where `docs.json` exists).
214122
</Accordion>
215123

216-
<Accordion title="Custom domain isn't connecting">
217-
Verify your CNAME record is correct and wait for DNS propagation. Use [DNSChecker](https://dnschecker.org) to verify your setup.
124+
<Accordion title="Custom domain not connecting">
125+
Verify your CNAME record and wait for DNS propagation. Use [DNSChecker](https://dnschecker.org) to verify.
218126
</Accordion>
219127
</AccordionGroup>
220128

221-
Still stuck? [Contact our support team](contact-support) for help.
129+
Need more help? [Contact support](contact-support) or check our [community forum](https://community.mintlify.com).

0 commit comments

Comments
 (0)