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,159 +93,165 @@ 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.Clone the repository created during setup
104
+
2. Open `index.mdx` and find the frontmatter:
105
105
106
106
```mdx index.mdx
107
107
---
108
108
title: "Introduction"
109
-
description: "This is the introduction to the documentation"
109
+
description: "Welcome to our 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"
118
-
description: "This is the introduction to the documentation"
117
+
title: "Welcome to our docs"
118
+
description: "Welcome to our documentation"
119
119
---
120
120
```
121
121
122
-
### Preview the changes
122
+
### Preview locally
123
123
124
-
To preview the changes locally, run the following command:
124
+
See your changes before publishing:
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 site running locally.
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 push and 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 changes go live 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 content creators and quick updates.
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
-
<imgalt="The Mintlify web editor in the visual editor mode"src="/images/quickstart/web-editor-light.png"className="block dark:hidden" />
164
-
<imgalt="The Mintlify web editor in the visual editor mode"src="/images/quickstart/web-editor-dark.png"className="hidden dark:block" />
169
+
<imgalt="The Mintlify web editor in visual mode"src="/images/quickstart/web-editor-light.png"className="block dark:hidden" />
170
+
<imgalt="The Mintlify web editor in visual mode"src="/images/quickstart/web-editor-dark.png"className="hidden dark:block" />
165
171
</Frame>
166
172
167
-
### Edit the documentation
173
+
### Edit visually
168
174
169
-
In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
175
+
Navigate to any file in the sidebar. Let's update the homepage:
170
176
171
-
Find and select `index.mdx` in the file explorer.
172
-
173
-
Then, in the editor, update the title field to "Hello World".
177
+
1. Click `index.mdx` in the file tree
178
+
2. Change the title field to "Welcome to our docs"
174
179
175
180
<Frame>
176
-
<imgalt="Editing in Web Editor"src="/images/quickstart/web-editor-editing-light.png"className="block dark:hidden" />
177
-
<imgalt="Editing in Web Editor"src="/images/quickstart/web-editor-editing-dark.png"className="hidden dark:block" />
181
+
<imgalt="Editing in the web editor"src="/images/quickstart/web-editor-editing-light.png"className="block dark:hidden" />
182
+
<imgalt="Editing in the 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 branded domain.
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.
Set up analytics, search, and other powerful features.
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 run">
246
+
Ensure you have Node.js v19+ installed. Run `node --version` to check. If you're on an older version, update Node.js and try again.
247
+
</Accordion>
248
+
<Accordiontitle="Changes aren't showing up">
249
+
Deployments usually take 1-3 minutes. Check your GitHub Actions tab or dashboard deployment logs for any build errors.
244
250
</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.
251
+
<Accordiontitle="Custom domain not working">
252
+
Double-check your CNAME record points to `cname.mintlify.app`. Use [DNSChecker](https://dnschecker.org) to verify the record is propagated globally.
247
253
</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.
254
+
<Accordiontitle="GitHub App permissions">
255
+
If you move your docs to a different repository, update the GitHub App installation to include the new repo.
![mintlify-development[bot]](https://avatars.githubusercontent.com/in/222252?v=4&size=40){kind=avatar}
0 commit comments