Skip to content

Commit a4c63bf

Browse files
mintlify-development[bot]mintlify-development[bot]
authored
Update quickstart.mdx
1 parent 0b5b2ea commit a4c63bf

File tree

1 file changed

+131
-142
lines changed

1 file changed

+131
-142
lines changed

‎quickstart.mdx‎

Lines changed: 131 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,240 @@
11
---
22
title: "Quickstart"
3-
description: "Deploy your documentation in minutes"
3+
description: "Build beautiful documentation in under 10 minutes"
44
icon: "rocket"
55
---
66

7-
This quickstart guide shows you how to set up and deploy your documentation site in minutes.
7+
Get your documentation site live in minutes with this step-by-step guide.
88

9-
After completing this guide, you will have a live documentation site ready to customize and expand.
9+
You'll go from zero to a fully deployed documentation site with custom branding and interactive features.
1010

1111
<Info>
1212

13-
**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
13+
**What you'll need**: A [Mintlify account](https://mintlify.com/start) and 10 minutes of your time.
1414

1515
</Info>
1616

17-
## Getting started
17+
## Create your site
1818

19-
After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
19+
Sign up for Mintlify and complete the onboarding flow. During setup, you'll:
20+
21+
1. Choose a project name (this becomes your initial URL)
22+
2. Connect your GitHub repository
23+
3. Select your documentation framework
24+
25+
Your site deploys automatically to:
2026

2127
```
22-
https://<your-project-name>.mintlify.app
28+
https://<project-name>.mintlify.app
2329
```
2430

25-
Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/).
26-
2731
<Frame>
28-
<img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify Domain" className="block dark:hidden" />
29-
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify Domain" className="hidden dark:block" />
32+
<img src="/images/quickstart/mintlify-domain-light.png" alt="Your live documentation URL" className="block dark:hidden" />
33+
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Your live documentation URL" className="hidden dark:block" />
3034
</Frame>
3135

32-
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.
36+
This URL is live immediately - share it with your team while you customize your docs.
3337

34-
### Install the GitHub App
38+
### Connect GitHub
3539

36-
Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
40+
The GitHub integration enables automatic deployments when you push changes.
3741

38-
Install the GitHub App by following the instructions from the onboarding checklist or your dashboard.
42+
From your dashboard:
3943

40-
1. Navigate to **Settings** in your Mintlify dashboard.
41-
2. Select **GitHub App** from the sidebar.
42-
3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page.
43-
4. Select the organization or user account where you want to install the app.
44-
5. Select the repositories that you want to connect.
44+
1. Go to **Settings** → **GitHub App**
45+
2. Click **Install GitHub App**
46+
3. Select your organization and repositories
47+
4. Authorize the connection
4548

4649
<Frame>
47-
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App Installation" className="block dark:hidden" />
48-
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App Installation" className="hidden dark:block" />
50+
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App setup" className="block dark:hidden" />
51+
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App setup" className="hidden dark:block" />
4952
</Frame>
5053

51-
<Info>
52-
Update the GitHub App permissions if you move your documentation to a different repository.
53-
</Info>
54-
55-
### Authorize your GitHub account
56-
57-
1. Navigate to **Settings** in your Mintlify dashboard.
58-
2. Select **My Profile** from the sidebar.
59-
3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page.
60-
61-
<Info>
62-
An admin for your GitHub organization may need to authorize your account depending on your organization settings.
63-
</Info>
64-
65-
## Editing workflows
54+
<Tip>
55+
You can change repository permissions later if you move your docs to a different repo.
56+
</Tip>
6657

67-
Mintlify offers two workflows for creating and maintaining your documentation:
58+
## Choose your workflow
6859

69-
<Card title="Code-based workflow" icon="terminal" horizontal href="#code-based-workflow">
70-
For users who prefer working with existing tools in their local environment. Click to jump to this section.
71-
</Card>
60+
Pick the editing experience that fits your team:
7261

73-
<Card title="Web editor workflow" icon="mouse-pointer-2" horizontal href="#web-editor-workflow">
74-
For users who prefer a visual interface in their web browser. Click to jump to this section.
75-
</Card>
62+
<CardGroup cols={2}>
63+
<Card title="Local development" icon="terminal" href="#local-development">
64+
Edit with your favorite code editor and Git workflow
65+
</Card>
66+
<Card title="Web editor" icon="mouse-pointer-2" href="#web-editor">
67+
Visual editing directly in your browser
68+
</Card>
69+
</CardGroup>
7670

77-
## Code-based workflow
71+
## Local development
7872

79-
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.
73+
Work with your documentation using familiar development tools and Git workflows.
8074

8175
### Install the CLI
8276

83-
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:
77+
Install the Mintlify CLI to preview changes locally:
8478

8579
<CodeGroup>
8680
```bash npm
87-
npm i -g mint
81+
npm install -g mint
82+
```
83+
84+
```bash yarn
85+
yarn global add mint
8886
```
8987

9088
```bash pnpm
9189
pnpm add -g mint
9290
```
9391
</CodeGroup>
9492

95-
<Info>
96-
You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
97-
</Info>
93+
<Warning>
94+
Requires Node.js 18 or higher. Run `node --version` to check your version.
95+
</Warning>
9896

99-
### Edit the documentation
97+
### Make your first edit
10098

101-
After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
99+
Let's customize your homepage:
102100

103-
1. Open your repository created during onboarding.
104-
2. Open `index.mdx` and locate the top of the file:
101+
1. Clone your repository locally
102+
2. Open `index.mdx` in your editor
103+
3. Update the frontmatter:
105104

106105
```mdx index.mdx
107106
---
108-
title: "Introduction"
109-
description: "This is the introduction to the documentation"
107+
title: "Welcome to our docs"
108+
description: "Everything you need to get started"
110109
---
111-
```
112110

113-
3. Update the `title` field to `"Hello World"`.
111+
# Getting started
114112

115-
```mdx index.mdx {2}
116-
---
117-
title: "Hello World"
118-
description: "This is the introduction to the documentation"
119-
---
113+
This is your new documentation homepage. Start editing to make it your own.
120114
```
121115

122-
### Preview the changes
116+
### Preview locally
123117

124-
To preview the changes locally, run the following command:
118+
Start the development server:
125119

126120
```bash
127121
mint dev
128122
```
129123

130-
Your preview will be available at `localhost:3000`.
124+
Your site runs at `http://localhost:3000` with hot reloading enabled.
131125

132126
<Frame>
133-
<img src="/images/quickstart/mintlify-dev-light.png" alt="Mintlify Dev" className="block dark:hidden" />
134-
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Mintlify Dev" className="hidden dark:block" />
127+
<img src="/images/quickstart/mintlify-dev-light.png" alt="Local development preview" className="block dark:hidden" />
128+
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Local development preview" className="hidden dark:block" />
135129
</Frame>
136130

137-
### Push the changes
138-
139-
When you are ready to publish your changes, push them to your repository.
140-
141-
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).
131+
### Deploy changes
142132

143-
After the deployment completes, your latest update will be available at `<your-project-name>.mintlify.app`.
133+
Push your changes to trigger automatic deployment:
144134

145-
<Card title="Jump to adding a custom domain" icon="arrow-down" href="#adding-a-custom-domain" horizontal>
146-
Optionally, skip the web editor workflow and jump to adding a custom domain.
147-
</Card>
135+
```bash
136+
git add .
137+
git commit -m "Update homepage"
138+
git push origin main
139+
```
148140

149-
## Web editor workflow
141+
Your changes go live in under 2 minutes. Track deployment status in your dashboard or GitHub Actions.
150142

151-
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.
143+
## Web editor
152144

153-
### Access the web editor
145+
Edit your documentation visually without leaving your browser.
154146

155-
1. Log in to your [dashboard](https://dashboard.mintlify.com).
156-
2. Select **Editor** on the left sidebar.
147+
### Open the editor
157148

158-
<Info>
159-
If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor.
160-
</Info>
149+
1. Go to your [Mintlify dashboard](https://dashboard.mintlify.com)
150+
2. Click **Editor** in the sidebar
161151

162152
<Frame>
163-
<img alt="The Mintlify web editor in the visual editor mode" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
164-
<img alt="The Mintlify web editor in the visual editor mode" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
153+
<img alt="Visual web editor interface" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
154+
<img alt="Visual web editor interface" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
165155
</Frame>
166156

167-
### Edit the documentation
168-
169-
In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
157+
### Edit content
170158

171-
Find and select `index.mdx` in the file explorer.
159+
Navigate to any page in the file tree and start editing:
172160

173-
Then, in the editor, update the title field to "Hello World".
161+
- Rich text formatting with the toolbar
162+
- Drag-and-drop components
163+
- Real-time preview
164+
- Collaborative editing
174165

175166
<Frame>
176-
<img alt="Editing in Web Editor" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
177-
<img alt="Editing in Web Editor" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
167+
<img alt="Editing content in the web editor" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
168+
<img alt="Editing content in the web editor" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
178169
</Frame>
179170

180171
<Tip>
181-
The editor provides a rich set of formatting tools and components. Type <kbd>/</kbd> in the editor to open the command menu and access these tools.
172+
Press <kbd>/</kbd> to open the component menu and add callouts, code blocks, and more.
182173
</Tip>
183174

184-
### Publish your changes
175+
### Publish instantly
185176

186-
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.
177+
Click **Publish** to deploy your changes immediately. No Git knowledge required.
187178

188-
<Tip>
189-
Use branches to preview and review changes through pull requests before deploying to your live site.
190-
</Tip>
179+
For team workflows, create branches and pull requests directly in the editor.
191180

192-
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).
181+
Learn more in our [web editor guide](/editor/getting-started).
193182

194-
## Adding a custom domain
183+
## Add a custom domain
195184

196-
While your `<your-project-name>.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation.
185+
Replace your `.mintlify.app` URL with your own domain for a professional look.
197186

198-
To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
199-
200-
<Frame>
201-
<img src="/images/quickstart/custom-domain-light.png" alt="Custom Domain" className="block dark:hidden" />
202-
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom Domain" className="hidden dark:block" />
203-
</Frame>
204-
205-
Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider.
187+
1. Go to **Settings** → **Custom Domain** in your dashboard
188+
2. Enter your domain (e.g., `docs.company.com`)
189+
3. Add this DNS record with your domain provider:
206190

207191
<Table>
208-
| Record Type | Name | Value | TTL |
209-
|-------------|------|-------|-----|
210-
| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
192+
| Type | Name | Value | TTL |
193+
|------|------|-------|-----|
194+
| CNAME | docs | cname.mintlify.app | 3600 |
211195
</Table>
212196

197+
<Frame>
198+
<img src="/images/quickstart/custom-domain-light.png" alt="Custom domain setup" className="block dark:hidden" />
199+
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom domain setup" className="hidden dark:block" />
200+
</Frame>
201+
213202
<Info>
214-
DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
203+
DNS changes typically take 5-30 minutes but can take up to 48 hours.
215204
</Info>
216205

217-
## Next steps
206+
## What's next?
218207

219-
Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
208+
Your documentation site is live! Here's how to make it amazing:
220209

221-
<Card title="Configure your global settings" icon="settings" href="settings" horizontal>
222-
Configure site-wide styling, navigation, integrations, and more with the `docs.json` file.
223-
</Card>
224-
<Card title="Customize your theme" icon="paintbrush" href="themes" horizontal>
225-
Learn how to customize colors, fonts, and the overall appearance of your documentation site.
226-
</Card>
227-
<Card title="Organize navigation" icon="map" href="navigation" horizontal>
228-
Structure your documentation with intuitive navigation to help users find what they need.
229-
</Card>
230-
<Card title="Add interactive components" icon="puzzle" href="/components/accordions" horizontal>
231-
Enhance your documentation with interactive components like accordions, tabs, and code samples.
232-
</Card>
233-
<Card title="Set up API references" icon="code" href="/api-playground/overview" horizontal>
234-
Create interactive API references with OpenAPI and AsyncAPI specifications.
235-
</Card>
210+
<CardGroup cols={2}>
211+
<Card title="Customize your brand" icon="paintbrush" href="themes">
212+
Colors, fonts, logos, and styling
213+
</Card>
214+
<Card title="Structure navigation" icon="map" href="navigation">
215+
Organize pages with groups and tabs
216+
</Card>
217+
<Card title="Add components" icon="puzzle" href="/components/accordions">
218+
Interactive elements and rich content
219+
</Card>
220+
<Card title="API documentation" icon="code" href="/api-playground/overview">
221+
Auto-generated from OpenAPI specs
222+
</Card>
223+
</CardGroup>
236224

237-
## Troubleshooting
238-
239-
If you encounter issues during the setup process, check these common troubleshooting solutions:
225+
## Need help?
240226

241227
<AccordionGroup>
242-
<Accordion title="Local preview not working">
243-
Make sure you have Node.js v19+ installed and that you run the `mint dev` command from the directory containing your `docs.json` file.
228+
<Accordion title="CLI not working?">
229+
Ensure you have Node.js 18+ and run `mint dev` from your project root (where `docs.json` lives).
230+
</Accordion>
231+
<Accordion title="Changes not deploying?">
232+
Check your GitHub Actions tab for build errors. Deployments typically take 1-3 minutes.
244233
</Accordion>
245-
<Accordion title="Changes not reflecting on live site">
246-
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.
234+
<Accordion title="Domain not connecting?">
235+
Verify your CNAME record points to `cname.mintlify.app`. Use [DNS Checker](https://dnschecker.org) to test propagation.
247236
</Accordion>
248-
<Accordion title="Custom domain not connecting">
249-
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.
237+
<Accordion title="Still stuck?">
238+
Join our [Discord community](https://discord.gg/mintlify) or email [email protected] for help.
250239
</Accordion>
251240
</AccordionGroup>

0 commit comments

Comments
 (0)