You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Visual editing interface - no local setup required.
75
75
</Card>
76
76
77
-
## Code-based workflow
77
+
## Local development
78
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.
79
+
Work with your documentation files directly in your development environment alongside your code.
80
80
81
-
### Install the CLI
81
+
### Get the CLI
82
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:
83
+
Install the Mintlify CLI to preview changes locally:
84
84
85
85
<CodeGroup>
86
86
```bash npm
@@ -93,15 +93,15 @@ To work locally with your documentation, install the Command Line Interface (CLI
93
93
</CodeGroup>
94
94
95
95
<Info>
96
-
You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
96
+
Requires Node.js v19 or higher. Having trouble? Check our troubleshooting section below.
97
97
</Info>
98
98
99
-
### Edit the documentation
99
+
### Make your first edit
100
100
101
-
After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
101
+
Let's update your homepage to see the workflow in action:
102
102
103
-
1. Open your repository created during onboarding.
104
-
2.Open`index.mdx` and locate the top of the file:
103
+
1. Open your documentation repository
104
+
2.Find`index.mdx` and look at the frontmatter:
105
105
106
106
```mdx index.mdx
107
107
---
@@ -110,142 +110,145 @@ description: "This is the introduction to the documentation"
110
110
---
111
111
```
112
112
113
-
3.Update the `title` field to `"Hello World"`.
113
+
3.Change the titleto something personal:
114
114
115
115
```mdx index.mdx {2}
116
116
---
117
-
title: "Hello World"
117
+
title: "Welcome to our docs"
118
118
description: "This is the introduction to the documentation"
119
119
---
120
120
```
121
121
122
-
### Preview the changes
122
+
### See it live locally
123
123
124
-
To preview the changes locally, run the following command:
124
+
Start the development server:
125
125
126
126
```bash
127
127
mint dev
128
128
```
129
129
130
-
Your preview will be available at `localhost:3000`.
130
+
Open `localhost:3000` to see your changes instantly.
When you are ready to publish your changes, push them to your repository.
141
+
```bash
142
+
git add .
143
+
git commit -m "Update homepage title"
144
+
git push
145
+
```
140
146
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).
147
+
Mintlify detects the changesand automatically rebuilds your site. Track deployment progress in your [dashboard](https://dashboard.mintlify.com) or GitHub Actions.
142
148
143
-
After the deployment completes, your latest update will be available at `<your-project-name>.mintlify.app`.
149
+
Your updates appear at `<your-project-name>.mintlify.app` within minutes.
144
150
145
-
<Cardtitle="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.
151
+
<Cardtitle="Skip to custom domain setup"icon="arrow-down"href="#custom-domain"horizontal>
152
+
Ready to use your own domain? Jump ahead.
147
153
</Card>
148
154
149
-
## Web editor workflow
155
+
## Browser editor
150
156
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.
157
+
Edit your documentation visually without any local setup - perfect for quick updates and non-technical team members.
152
158
153
-
### Access the web editor
159
+
### Open the editor
154
160
155
-
1. Log in to your [dashboard](https://dashboard.mintlify.com).
156
-
2.Select**Editor**on the left sidebar.
161
+
1. Log into your [dashboard](https://dashboard.mintlify.com)
162
+
2.Click**Editor**in the sidebar
157
163
158
164
<Info>
159
-
If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor.
165
+
First time? You'll be prompted to install the GitHub App if you haven't already.
160
166
</Info>
161
167
162
168
<Frame>
163
169
<imgalt="The Mintlify web editor in the visual editor mode"src="/images/quickstart/web-editor-light.png"className="block dark:hidden" />
164
170
<imgalt="The Mintlify web editor in the visual editor mode"src="/images/quickstart/web-editor-dark.png"className="hidden dark:block" />
165
171
</Frame>
166
172
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:
173
+
### Edit visually
170
174
171
-
Find and select `index.mdx` in the file explorer.
175
+
Navigate to any page using the file tree on the left. Let's update the homepage:
172
176
173
-
Then, in the editor, update the title field to "Hello World".
177
+
1. Click `index.mdx` in the file explorer
178
+
2. Change the title field to "Welcome to our docs"
174
179
175
180
<Frame>
176
181
<imgalt="Editing in Web Editor"src="/images/quickstart/web-editor-editing-light.png"className="block dark:hidden" />
177
182
<imgalt="Editing in Web Editor"src="/images/quickstart/web-editor-editing-dark.png"className="hidden dark:block" />
178
183
</Frame>
179
184
180
185
<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.
186
+
Press <kbd>/</kbd> anywhere in the editor to open the component menu and add rich content like callouts, code blocks, and more.
182
187
</Tip>
183
188
184
-
### Publish your changes
189
+
### Go live instantly
185
190
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.
191
+
Click **Publish** in the top-right corner. Your changes deploy immediately to your live site.
187
192
188
193
<Tip>
189
-
Use branches to preview and review changes through pull requests before deploying to your live site.
194
+
Use branches for collaborative editing and review workflows before publishing to production.
190
195
</Tip>
191
196
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).
197
+
Learn more about advanced editor features in our [web editor guide](/editor/getting-started).
193
198
194
-
## Adding a custom domain
199
+
## Custom domain
195
200
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.
201
+
Replace your `.mintlify.app`URL with your own domain for a professional look.
197
202
198
-
To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard.
203
+
Navigate to [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) in your dashboard.
Enhance your documentation with interactive components like accordions, tabs, and code samples.
235
+
<Cardtitle="Configure site settings"icon="settings"href="settings"horizontal>
236
+
Set up analytics, SEO, custom scripts, and integrations.
232
237
</Card>
233
-
<Cardtitle="Set up API references"icon="code"href="/api-playground/overview"horizontal>
234
-
Create interactive API references with OpenAPI and AsyncAPI specifications.
238
+
<Cardtitle="Build API docs"icon="code"href="/api-playground/overview"horizontal>
239
+
Generate interactive API references from OpenAPI specs.
235
240
</Card>
236
241
237
-
## Troubleshooting
238
-
239
-
If you encounter issues during the setup process, check these common troubleshooting solutions:
242
+
## Common issues
240
243
241
244
<AccordionGroup>
242
-
<Accordiontitle="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.
245
+
<Accordiontitle="CLI won't install or start">
246
+
Ensure you have Node.js v19+ installed. Run `node --version` to check. If using an older version, update Node.js and try again.
244
247
</Accordion>
245
-
<Accordiontitle="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.
248
+
<Accordiontitle="Site not updating after push">
249
+
Check your GitHub Actions tab for build errors. Deployments typically take 2-5 minutes. Verify your GitHub App has access to the correct repository.
247
250
</Accordion>
248
-
<Accordiontitle="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.
251
+
<Accordiontitle="Custom domain not working">
252
+
Double-check your CNAME record points to `cname.mintlify.app`. Use [DNSChecker](https://dnschecker.org) to verify DNS propagation. Contact support if issues persist after 48 hours.
![mintlify-development[bot]](https://avatars.githubusercontent.com/in/222252?v=4&size=40){kind=avatar}
0 commit comments