Skip to content

Commit 3ca0abd

Browse files
mintlify-development[bot]mintlify-development[bot]
authored
Update quickstart.mdx
1 parent ef880d1 commit 3ca0abd

File tree

1 file changed

+121
-146
lines changed

1 file changed

+121
-146
lines changed

‎quickstart.mdx‎

Lines changed: 121 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,226 @@
11
---
22
title: "Quickstart"
3-
description: "Deploy your documentation in minutes"
3+
description: "Get your documentation site live 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.
8-
9-
After completing this guide, you will have a live documentation site ready to customize and expand.
7+
Build and deploy beautiful documentation in minutes. This guide walks you through creating your first documentation site from setup to deployment.
108

119
<Info>
12-
13-
**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
14-
10+
**Before you start**: You'll need a [Mintlify account](https://mintlify.com/start). The onboarding process creates your first project automatically.
1511
</Info>
1612

17-
## Getting started
13+
## Your site is already live
1814

19-
After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
15+
Once you complete onboarding, your documentation site is automatically deployed at:
2016

2117
```
2218
https://<your-project-name>.mintlify.app
2319
```
2420

25-
Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/).
21+
You can find this URL on your [dashboard overview](https://dashboard.mintlify.com/).
2622

2723
<Frame>
2824
<img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify Domain" className="block dark:hidden" />
2925
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify Domain" className="hidden dark:block" />
3026
</Frame>
3127

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.
28+
## Connect your GitHub repository
3329

34-
### Install the GitHub App
35-
36-
Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
30+
Link your GitHub repository to enable automatic deployments when you push changes.
3731

38-
Install the GitHub App by following the instructions from the onboarding checklist or your dashboard.
32+
### Install the GitHub App
3933

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.
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
4538

4639
<Frame>
4740
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App Installation" className="block dark:hidden" />
4841
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App Installation" className="hidden dark:block" />
4942
</Frame>
5043

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
44+
### Authorize your account
5645

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.
46+
1. Navigate to **Settings** → **My Profile**
47+
2. Click **Authorize GitHub account**
48+
3. Complete the authorization process
6049

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
50+
<Tip>
51+
Organization admins may need to approve the authorization depending on your GitHub settings.
52+
</Tip>
6653

67-
Mintlify offers two workflows for creating and maintaining your documentation:
54+
## Choose your editing workflow
6855

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>
56+
Pick the workflow that matches your team's preferences:
7257

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>
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
61+
</Card>
62+
<Card title="Web editor" icon="mouse-pointer-2" href="#web-editor">
63+
Visual editing directly in your browser with instant previews
64+
</Card>
65+
</CardGroup>
7666

77-
## Code-based workflow
67+
## Local development
7868

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.
69+
Perfect for developers who want to integrate documentation into their existing workflow.
8070

8171
### Install the CLI
8272

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:
73+
Install the Mintlify CLI to work with your documentation locally:
8474

8575
<CodeGroup>
86-
```bash npm
87-
npm i -g mint
88-
```
76+
```bash npm
77+
npm i -g mint
78+
```
8979

90-
```bash pnpm
91-
pnpm add -g mint
92-
```
80+
```bash pnpm
81+
pnpm add -g mint
82+
```
9383
</CodeGroup>
9484

95-
<Info>
96-
You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
97-
</Info>
85+
<Warning>
86+
Requires Node.js v19 or higher. Check your version with `node --version`.
87+
</Warning>
9888

99-
### Edit the documentation
89+
### Make your first edit
10090

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

103-
1. Open your repository created during onboarding.
104-
2. Open `index.mdx` and locate the top of the file:
93+
1. Open your documentation repository
94+
2. Edit `index.mdx` and change the title:
10595

10696
```mdx index.mdx
10797
---
108-
title: "Introduction"
109-
description: "This is the introduction to the documentation"
110-
---
111-
```
112-
113-
3. Update the `title` field to `"Hello World"`.
114-
115-
```mdx index.mdx {2}
116-
---
117-
title: "Hello World"
98+
title: "Welcome to our docs" // [!code ++]
99+
title: "Introduction" // [!code --]
118100
description: "This is the introduction to the documentation"
119101
---
120102
```
121103

122-
### Preview the changes
104+
### Preview locally
123105

124-
To preview the changes locally, run the following command:
106+
Start the development server to see your changes:
125107

126108
```bash
127109
mint dev
128110
```
129111

130-
Your preview will be available at `localhost:3000`.
112+
Your site will be available at `http://localhost:3000`.
131113

132114
<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" />
115+
<img src="/images/quickstart/mintlify-dev-light.png" alt="Local development preview" className="block dark:hidden" />
116+
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Local development preview" className="hidden dark:block" />
135117
</Frame>
136118

137-
### Push the changes
119+
### Deploy your changes
138120

139-
When you are ready to publish your changes, push them to your repository.
121+
Push your changes to GitHub. Mintlify automatically builds and deploys your updates.
140122

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>
123+
```bash
124+
git add .
125+
git commit -m "Update homepage title"
126+
git push origin main
127+
```
148128

149-
## Web editor workflow
129+
Monitor deployment status in your GitHub repository or the Mintlify dashboard.
150130

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.
131+
## Web editor
152132

153-
### Access the web editor
133+
Ideal for content creators who prefer visual editing without technical setup.
154134

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

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>
137+
1. Open your [Mintlify dashboard](https://dashboard.mintlify.com)
138+
2. Click **Editor** in the sidebar
161139

162140
<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" />
141+
<img alt="Mintlify web editor interface" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
142+
<img alt="Mintlify web editor interface" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
165143
</Frame>
166144

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:
170-
171-
Find and select `index.mdx` in the file explorer.
145+
### Edit your content
172146

173-
Then, in the editor, update the title field to "Hello World".
147+
1. Select `index.mdx` from the file explorer
148+
2. Update the title field to "Welcome to our docs"
149+
3. Use the rich text editor or switch to markdown mode
174150

175151
<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" />
152+
<img alt="Editing content in the web editor" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
153+
<img alt="Editing content in the web editor" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
178154
</Frame>
179155

180156
<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.
157+
Press `/` to open the command menu and access formatting tools, components, and shortcuts.
182158
</Tip>
183159

184-
### Publish your changes
160+
### Publish instantly
185161

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.
162+
Click **Publish** in the top-right corner. Your changes go live immediately.
187163

188-
<Tip>
189-
Use branches to preview and review changes through pull requests before deploying to your live site.
190-
</Tip>
191-
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).
164+
<Info>
165+
Use branches for collaborative editing and review workflows. Learn more in our [web editor guide](/editor/getting-started).
166+
</Info>
193167

194-
## Adding a custom domain
168+
## Add a custom domain
195169

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.
170+
Replace your `.mintlify.app` subdomain with your own domain for a professional look.
197171

198-
To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
172+
1. Go to **Settings** → **Custom Domain** in your dashboard
173+
2. Enter your domain (e.g., `docs.yourcompany.com`)
174+
3. Add the CNAME record to your DNS provider:
199175

200176
<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" />
177+
<img src="/images/quickstart/custom-domain-light.png" alt="Custom domain setup" className="block dark:hidden" />
178+
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom domain setup" className="hidden dark:block" />
203179
</Frame>
204180

205-
Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider.
206-
207-
<Table>
208181
| Record Type | Name | Value | TTL |
209182
|-------------|------|-------|-----|
210-
| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
211-
</Table>
183+
| CNAME | docs | cname.mintlify.app | 3600 |
212184

213-
<Info>
214-
DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
215-
</Info>
185+
<Warning>
186+
DNS changes can take up to 48 hours to propagate globally.
187+
</Warning>
216188

217-
## Next steps
189+
## What's next?
218190

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

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>
193+
<CardGroup cols={2}>
194+
<Card title="Customize your theme" icon="paintbrush" href="/themes">
195+
Brand your docs with custom colors, fonts, and styling
196+
</Card>
197+
<Card title="Structure navigation" icon="map" href="/navigation">
198+
Organize pages with groups, tabs, and hierarchical navigation
199+
</Card>
200+
<Card title="Add components" icon="puzzle" href="/components/accordions">
201+
Enhance content with interactive elements and rich media
202+
</Card>
203+
<Card title="API documentation" icon="code" href="/api-playground/overview">
204+
Generate interactive API references from OpenAPI specs
205+
</Card>
206+
</CardGroup>
236207

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

241210
<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.
211+
<Accordion title="Local preview isn't working">
212+
Ensure you have Node.js v19+ and run `mint dev` from your project root directory containing `docs.json`.
213+
</Accordion>
214+
215+
<Accordion title="Changes aren't appearing on my live site">
216+
Check your GitHub Actions tab for build errors. Deployments typically take 1-3 minutes.
244217
</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.
218+
219+
<Accordion title="Custom domain won't connect">
220+
Verify your CNAME record is correct and allow time for DNS propagation. Use [DNSChecker](https://dnschecker.org) to verify.
247221
</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.
222+
223+
<Accordion title="Still stuck?">
224+
Contact our support team through the dashboard or check our [troubleshooting guides](/contact-support).
250225
</Accordion>
251-
</AccordionGroup>
226+
</AccordionGroup>

0 commit comments

Comments
 (0)