Skip to content

Commit e7e20ea

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

File tree

1 file changed

+132
-142
lines changed

1 file changed

+132
-142
lines changed

‎quickstart.mdx‎

Lines changed: 132 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,241 @@
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 source folder
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 files locally using familiar development tools.
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. Check your version with `node --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 update 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 connected repository
102+
2. Open `index.mdx` in your editor
103+
3. Change the title in 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+
Your documentation content goes here...
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+
Open `http://localhost:3000` to see your changes in real-time.
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 preview" className="block dark:hidden" />
128+
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Local preview" className="hidden dark:block" />
135129
</Frame>
136130

137-
### Push the changes
131+
### Deploy changes
138132

139-
When you are ready to publish your changes, push them to your repository.
133+
Push your changes to GitHub:
140134

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).
142-
143-
After the deployment completes, your latest update will be available at `<your-project-name>.mintlify.app`.
144-
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 title"
138+
git push
139+
```
148140

149-
## Web editor workflow
141+
Mintlify automatically builds and deploys your updates. Check the 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="Web editor interface" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
154+
<img alt="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+
- Live preview as you type
163+
- Drag-and-drop components
174164

175165
<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" />
166+
<img alt="Editing content" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
167+
<img alt="Editing content" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
178168
</Frame>
179169

180170
<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.
171+
Press <kbd>/</kbd> to open the component menu and add callouts, code blocks, and more.
182172
</Tip>
183173

184-
### Publish your changes
174+
### Publish instantly
185175

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.
176+
Click **Publish** to deploy your changes immediately. No Git commands required.
187177

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

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

194-
## Adding a custom domain
182+
## Add a custom domain
195183

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.
184+
Replace your `.mintlify.app` URL with your own domain.
197185

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.
186+
1. Go to **Settings** → **Custom Domain** in your dashboard
187+
2. Enter your domain (e.g., `docs.company.com`)
188+
3. Add this DNS record with your domain provider:
206189

207190
<Table>
208-
| Record Type | Name | Value | TTL |
209-
|-------------|------|-------|-----|
210-
| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
191+
| Type | Name | Value | TTL |
192+
|------|------|-------|-----|
193+
| CNAME | docs | cname.mintlify.app | 3600 |
211194
</Table>
212195

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

217-
## Next steps
218-
219-
Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
205+
## What's next?
220206

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>
207+
Your documentation site is live! Here's how to make it even better:
236208

237-
## Troubleshooting
209+
<CardGroup cols={2}>
210+
<Card title="Customize your brand" icon="palette" href="themes">
211+
Colors, fonts, and logos that match your company
212+
</Card>
213+
<Card title="Structure navigation" icon="sitemap" href="navigation">
214+
Organize pages with groups, tabs, and sections
215+
</Card>
216+
<Card title="Add components" icon="blocks" href="/components/accordions">
217+
Interactive elements like tabs, callouts, and code blocks
218+
</Card>
219+
<Card title="API documentation" icon="code" href="/api-playground/overview">
220+
Auto-generated API references from OpenAPI specs
221+
</Card>
222+
</CardGroup>
238223

239-
If you encounter issues during the setup process, check these common troubleshooting solutions:
224+
## Need help?
240225

241226
<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.
227+
<Accordion title="Preview not loading locally">
228+
Ensure you're running `mint dev` from the folder containing `docs.json` and that Node.js 18+ is installed.
244229
</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.
230+
<Accordion title="Changes not appearing on live site">
231+
Check your GitHub Actions tab for build errors. Deployments typically take 1-3 minutes.
247232
</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.
233+
<Accordion title="Custom domain not working">
234+
Verify your CNAME record is correct and wait for DNS propagation. Use [DNS Checker](https://dnschecker.org) to verify.
235+
</Accordion>
236+
<Accordion title="GitHub App permissions">
237+
Update permissions in your GitHub organization settings if you can't access certain repositories.
250238
</Accordion>
251239
</AccordionGroup>
240+
241+
Still stuck? [Contact our support team](mailto:[email protected]) - we're here to help.

0 commit comments

Comments
 (0)