Skip to content

Commit 43ddef8

Browse files
cursoragenthandotdev
cursoragent
and
handotdev
committed
Refactor: Simplify quickstart guide and improve clarity
Co-authored-by: han <[email protected]>
1 parent 0b5b2ea commit 43ddef8

File tree

1 file changed

+147
-202
lines changed

1 file changed

+147
-202
lines changed

‎quickstart.mdx‎

Lines changed: 147 additions & 202 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,196 @@
11
---
22
title: "Quickstart"
3-
description: "Deploy your documentation in minutes"
3+
description: "Deploy beautiful documentation in under 5 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+
Deploy your documentation site and start creating beautiful docs in just a few minutes.
108

119
<Info>
12-
13-
**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
14-
10+
**Before you begin**: Create your [Mintlify account](https://mintlify.com/start) and complete the onboarding process.
1511
</Info>
1612

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

19-
After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format:
15+
After onboarding, your documentation 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/).
26-
27-
<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" />
30-
</Frame>
21+
<Check>
22+
Your documentation site is already live and ready to share with your team.
23+
</Check>
3124

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.
33-
34-
### Install the GitHub App
35-
36-
Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
37-
38-
Install the GitHub App by following the instructions from the onboarding checklist or your dashboard.
39-
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.
25+
Find your exact URL in the [dashboard](https://dashboard.mintlify.com/) Overview page.
4526

4627
<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" />
28+
<img src="/images/quickstart/mintlify-domain-light.png" alt="Live documentation URL in dashboard" className="block dark:hidden" />
29+
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Live documentation URL in dashboard" className="hidden dark:block" />
4930
</Frame>
5031

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
66-
67-
Mintlify offers two workflows for creating and maintaining your documentation:
32+
## Choose your workflow
6833

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.
34+
<CardGroup cols={2}>
35+
<Card title="Web editor" icon="mouse-pointer-2" href="#web-editor-workflow">
36+
Visual editing in your browser. No setup required.
7137
</Card>
7238

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.
39+
<Card title="Code-based" icon="terminal" href="#code-based-workflow">
40+
Local development with Git integration.
7541
</Card>
42+
</CardGroup>
7643

77-
## Code-based workflow
78-
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.
80-
81-
### Install the CLI
82-
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:
44+
## Web editor workflow
8445

85-
<CodeGroup>
86-
```bash npm
87-
npm i -g mint
46+
The fastest way to create and edit documentation.
47+
48+
<Steps>
49+
<Step title="Open the editor">
50+
Navigate to **Editor** in your [dashboard](https://dashboard.mintlify.com).
51+
52+
<Tip>
53+
The GitHub App will install automatically when you first open the editor.
54+
</Tip>
55+
</Step>
56+
57+
<Step title="Edit your first page">
58+
Select `index.mdx` and change the title to "Hello Mintlify".
59+
60+
<Frame>
61+
<img alt="Editing documentation in the web editor" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
62+
<img alt="Editing documentation in the web editor" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
63+
</Frame>
64+
65+
<Tip>
66+
Press <kbd>/</kbd> in the editor to access components, formatting, and more.
67+
</Tip>
68+
</Step>
69+
70+
<Step title="Publish your changes">
71+
Select **Publish** to deploy your changes instantly.
72+
73+
<Check>
74+
Your changes are now live at your documentation URL.
75+
</Check>
76+
</Step>
77+
</Steps>
78+
79+
## Code-based workflow
80+
81+
For teams who prefer local development and Git workflows.
82+
83+
<Steps>
84+
<Step title="Install the CLI">
85+
<CodeGroup>
86+
```bash npm
87+
npm i -g mint
88+
```
89+
90+
```bash pnpm
91+
pnpm add -g mint
92+
```
93+
</CodeGroup>
94+
95+
<Info>
96+
Requires Node.js 19+. Having trouble? Check our [troubleshooting guide](#troubleshooting).
97+
</Info>
98+
</Step>
99+
100+
<Step title="Set up GitHub integration">
101+
In your dashboard:
102+
1. Go to **Settings** → **GitHub App**
103+
2. Select **Install GitHub App**
104+
3. Choose your repositories
105+
106+
<Info>
107+
Admin approval may be required for organization repositories.
108+
</Info>
109+
</Step>
110+
111+
<Step title="Edit locally">
112+
Clone your repository and make changes:
113+
114+
```mdx index.mdx
115+
---
116+
title: "Hello Mintlify"
117+
description: "Welcome to our documentation"
118+
---
88119
```
89120

90-
```bash pnpm
91-
pnpm add -g mint
121+
Preview changes with:
122+
```bash
123+
mint dev
92124
```
93-
</CodeGroup>
94-
95-
<Info>
96-
You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
97-
</Info>
98-
99-
### Edit the documentation
100-
101-
After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
102-
103-
1. Open your repository created during onboarding.
104-
2. Open `index.mdx` and locate the top of the file:
105-
106-
```mdx index.mdx
107-
---
108-
title: "Introduction"
109-
description: "This is the introduction to the documentation"
110-
---
111-
```
112-
113-
3. Update the `title` field to `"Hello World"`.
114125

115-
```mdx index.mdx {2}
116-
---
117-
title: "Hello World"
118-
description: "This is the introduction to the documentation"
119-
---
120-
```
126+
<Check>
127+
Your preview is available at `localhost:3000`.
128+
</Check>
129+
</Step>
121130

122-
### Preview the changes
131+
<Step title="Deploy changes">
132+
Push to your repository. Mintlify automatically builds and deploys your updates.
123133

124-
To preview the changes locally, run the following command:
134+
<Check>
135+
Monitor deployment status in GitHub Actions or your dashboard.
136+
</Check>
137+
</Step>
138+
</Steps>
125139

126-
```bash
127-
mint dev
128-
```
140+
## Add a custom domain
129141

130-
Your preview will be available at `localhost:3000`.
142+
Ready to use your own domain? Navigate to [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) in your dashboard.
131143

132-
<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" />
135-
</Frame>
144+
<Steps>
145+
<Step title="Enter your domain">
146+
Add your domain (like `docs.yourcompany.com`).
147+
</Step>
136148

137-
### Push the changes
149+
<Step title="Configure DNS">
150+
Add this CNAME record with your DNS provider:
138151

139-
When you are ready to publish your changes, push them to your repository.
152+
| Record | Name | Value | TTL |
153+
|--------|------|-------|-----|
154+
| CNAME | docs | cname.mintlify.app | 3600 |
140155

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).
156+
<Info>
157+
DNS changes can take up to 48 hours, but often complete within minutes.
158+
</Info>
159+
</Step>
160+
</Steps>
142161

143-
After the deployment completes, your latest update will be available at `<your-project-name>.mintlify.app`.
162+
## What's next?
144163

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.
164+
<CardGroup cols={2}>
165+
<Card title="Customize your site" icon="paintbrush" href="themes">
166+
Configure colors, fonts, and styling to match your brand.
147167
</Card>
148168

149-
## Web editor workflow
150-
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.
152-
153-
### Access the web editor
154-
155-
1. Log in to your [dashboard](https://dashboard.mintlify.com).
156-
2. Select **Editor** on the left sidebar.
157-
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>
161-
162-
<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" />
165-
</Frame>
166-
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.
172-
173-
Then, in the editor, update the title field to "Hello World".
174-
175-
<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" />
178-
</Frame>
179-
180-
<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.
182-
</Tip>
183-
184-
### Publish your changes
185-
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.
187-
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).
193-
194-
## Adding a custom domain
195-
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.
197-
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.
206-
207-
<Table>
208-
| Record Type | Name | Value | TTL |
209-
|-------------|------|-------|-----|
210-
| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
211-
</Table>
212-
213-
<Info>
214-
DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
215-
</Info>
216-
217-
## Next steps
218-
219-
Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
220-
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.
169+
<Card title="Organize navigation" icon="map" href="navigation">
170+
Structure your documentation with intuitive navigation.
223171
</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.
172+
173+
<Card title="Add components" icon="puzzle" href="/components/accordions">
174+
Enhance content with interactive components and code samples.
232175
</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.
176+
177+
<Card title="Set up API docs" icon="code" href="/api-playground/overview">
178+
Create interactive API references with OpenAPI specs.
235179
</Card>
180+
</CardGroup>
236181

237182
## Troubleshooting
238183

239-
If you encounter issues during the setup process, check these common troubleshooting solutions:
240-
241184
<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.
244-
</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.
247-
</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.
250-
</Accordion>
251-
</AccordionGroup>
185+
<Accordion title="Local preview not working">
186+
Ensure you have Node.js 19+ and run `mint dev` from your docs directory containing `docs.json`.
187+
</Accordion>
188+
189+
<Accordion title="Changes not deploying">
190+
Deployment takes 1-3 minutes. Check GitHub Actions or dashboard logs for build errors.
191+
</Accordion>
192+
193+
<Accordion title="Custom domain issues">
194+
Verify DNS records are correct and allow time for propagation. Use [DNSChecker](https://dnschecker.org) to verify your CNAME.
195+
</Accordion>
196+
</AccordionGroup>

0 commit comments

Comments
 (0)