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
@@ -4,150 +4,238 @@ description: "Deploy your documentation in minutes"
4
4
icon: "rocket"
5
5
---
6
6
7
+
This quickstart guide will walk you through the process of setting up and deploying your documentation site in just a few minutes.
8
+
9
+
By the end of this guide, you'll have a live documentation site that's ready to customize and expand.
10
+
11
+
<Info>
12
+
13
+
**Prerequisites**: Before you begin, make sure to [create an account](https://mintlify.com/signup) and complete onboarding.
14
+
15
+
</Info>
16
+
7
17
## Getting Started
8
18
9
-
Welcome\! Follow the instructions below to learn how to deploy, update and
10
-
supercharge your documentation with Mintlify.
19
+
Once you've completed the onboarding process, your documentation site will be automatically deployed to a unique URL with the following format.
11
20
12
-
### Creating the Repository
21
+
```
22
+
https://<your-project-name>.mintlify.app
23
+
```
13
24
14
-
Mintlify docs are rendered from MDX files and configurations defined in our
15
-
[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
16
-
your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
25
+
You can find your URL from the Overview page of the dashboard.
17
26
18
-
<AccordionGroup>
19
-
<Accordiontitle="Install the GitHub app">
20
-
Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
This URL is instantly available and will update whenever you make changes to your documentation. It's perfect for testing and sharing with your team during development.
49
33
50
-
Mintlify enables you to easily customize the style, structure, and content of
51
-
your docs.
34
+
## Development Workflows
52
35
53
-
<AccordionGroup>
54
-
<Accordiontitle="Editing locally (recommended for developers)">
2. Once git is installed, clone your docs repository using `git clone <your-repo>`. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
57
-
3. Use your favorite IDE to open the repository.
58
-
4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.
59
-
60
-
Learn more about this in our [local development guide](/installation).
61
-
</Accordion>
62
-
<Accordiontitle="Editing with the web editor">
63
-
Learn more about how to use the web editor on our [guide](/editor).
64
-
</Accordion>
65
-
<Accordiontitle="Customizing to your brand">
66
-
Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations:
67
-
68
-
```json
69
-
"name": "Your Company"
70
-
"logo": {
71
-
"light": "/logo/light.svg",
72
-
"dark": "/logo/dark.svg",
73
-
"href": "https://yourcompany.com"
74
-
},
75
-
"favicon": "/favicon.svg",
76
-
"colors": {
77
-
"primary": "#2AB673",
78
-
"light": "#55D799",
79
-
"dark": "#117866",
80
-
},
81
-
```
82
-
83
-
A full list of supported configurations can be found at [global settings](/core-concepts/settings).
84
-
</Accordion>
85
-
<Accordiontitle="Adding content">
86
-
Add content with simple MDX files. Initiate your pages with this template:
87
-
88
-
```md
89
-
---
90
-
title: "Page Title"
91
-
sidebarTitle: "Sidebar title (optional - if different from page title)"
92
-
description: "Subtitle (optional)"
93
-
---
94
-
```
95
-
96
-
Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
97
-
</Accordion>
98
-
<Accordiontitle="Pushing changes">
99
-
Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`.
122
-
123
-
For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview).
124
-
</Accordion>
125
-
<Accordiontitle="Adding analytics">
126
-
Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
127
-
128
-
We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
129
-
</Accordion>
130
-
</AccordionGroup>
36
+
Mintlify offers two different workflows for creating and maintaining your documentation.
For those who prefer a visual interface. [Jump to section](#web-editor-workflow)
44
+
</Card>
45
+
46
+
## Code-Based Workflow
47
+
48
+
The code-based workflow integrates with your existing development environment and Git repositories, making it ideal for technical teams who want to manage documentation alongside their code.
49
+
50
+
### Install the CLI
51
+
52
+
To work locally with your documentation, install the Mintlify Command Line Interface (CLI) by running the following command in your terminal:
53
+
54
+
<CodeGroup>
55
+
56
+
```bash npm
57
+
npm install -g mintlify
58
+
```
59
+
60
+
61
+
```bash yarn
62
+
yarn global add mintlify
63
+
```
64
+
65
+
66
+
```bash pnpm
67
+
pnpm add -g mintlify
68
+
```
69
+
70
+
</CodeGroup>
71
+
72
+
<Info>
73
+
You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide.
74
+
</Info>
131
75
76
+
### Install the GitHub App
77
+
78
+
Mintlify provides a GitHub App that automates the deployment process when you push changes to your repository.
79
+
80
+
You can install the GitHub App by following the instructions from the onboarding checklist or by navigating to `Settings` > `Organization` > `GitHub`.
81
+
82
+
Click `Install GitHub App`. Select the repositories you want to connect.
When you're ready to publish your changes, simply push the changes to your repository.
134
+
135
+
Mintlify will automatically detect the changes, build your documentation, and deploy the updates to your site. You can monitor the deployment status in your GitHub repository's commit history or the [dashboard](https://dashboard.mintlify.com).
136
+
137
+
Once the deployment is complete, your last update will be available at `<your-project-name>.mintlify.app`.
138
+
139
+
<Cardtitle="Jump to adding a custom domain"icon="arrow-down"href="#adding-a-custom-domain"horizontal>
140
+
Skip the web editor workflow and jump to adding a custom domain.
141
+
</Card>
142
+
143
+
## Web Editor Workflow
144
+
145
+
The web editor workflow provides an intuitive interface for creating and editing documentation without requiring local development tools. It's ideal for non-technical team members or for making quick updates.
146
+
147
+
<Steps>
148
+
<Steptitle="Access the Web Editor">
149
+
Log in to your Mintlify Dashboard and select your project. Click the Edit button to open the web editor.
In the web editor, you can navigate your documentation files in the sidebar. Let's update the introduction page:
156
+
Find and click on introduction.mdx in the file explorer
157
+
In the visual editor, update the title field to "Hello World"
158
+
You'll see your changes reflected in the live preview on the right
159
+
<Framecaption="Web Editor Interface">
160
+
<imgalt="Editing in Web Editor"src="/images/web-editor-interface.png" />
161
+
</Frame>
162
+
<Tip>
163
+
The editor provides a rich set of formatting tools and components. Access them by clicking the "+" button or typing "/" in the editor to open the command menu.
164
+
</Tip>
165
+
</Step>
166
+
<Steptitle="Publish Your Changes">
167
+
When you're satisfied with your edits:
168
+
Click the Publish button in the top-right corner
169
+
Review your changes in the confirmation dialog
170
+
Add a commit message describing your updates
171
+
Click Confirm and Publish
172
+
Your changes will be deployed immediately to your documentation site.
We provide a white-glove migration service as part of our Enterprise plan.
134
-
Interested? You can request it by [contacting us](mailto:[email protected]).
177
+
For teams using Git workflows, the web editor can create branches and pull requests instead of publishing directly to the main branch. This allows for proper review processes.
178
+
</Note>
179
+
</Step>
180
+
<Steptitle="Add a Custom Domain (Optional)">
181
+
Just as with the code-based workflow, you can add a custom domain through the dashboard:
182
+
From your Mintlify dashboard, go to Settings > Custom Domain
183
+
Enter your domain (e.g., docs.yourcompany.com)
184
+
Follow the provided instructions to configure DNS settings with your domain provider
185
+
</Step>
186
+
</Steps>
187
+
For more details about using the web editor, including advanced features like slash commands and image uploads, see our Web Editor documentation.
188
+
Next Steps
189
+
Congratulations! You've successfully deployed your first documentation site with Mintlify. Here are some suggested next steps to enhance your documentation:
190
+
<CardGroupcols={2}>
191
+
<Cardtitle="Customize Your Theme"icon="paintbrush"href="/core-concepts/styling/themes">
192
+
Learn how to customize colors, fonts, and the overall appearance of your documentation site.
DNS changes can take up to 48 hours to propagate, though they often complete much sooner.
135
220
</Note>
136
221
137
-
### Publishing
138
-
139
-
<Accordiontitle="Adding a custom domain">
140
-
Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
222
+
## Troubleshooting
141
223
142
-
Navigate to your [dashboard settings](https://dashboard.mintlify.com/settings) to add a custom domain.
224
+
If you encounter any issues during the setup process, check our common troubleshooting solutions:
143
225
144
-
<Frame>
145
-
146
-
</Frame>
226
+
<AccordionGroup>
227
+
<Accordiontitle="Local preview not working">
228
+
Make sure you have Node.js v19+ installed and that you're running the mintlify dev command from the directory containing your docs.json file.
229
+
</Accordion>
230
+
<Accordiontitle="Changes not reflecting on live site">
231
+
Deployment typically takes 1-2 minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors.
232
+
</Accordion>
233
+
<Accordiontitle="Custom domain not connecting">
234
+
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 to verify your CNAME record.
147
235
</Accordion>
236
+
</AccordionGroup>
237
+
148
238
149
-
Congrats, you've set up your documentation on Mintlify\!
150
239
151
-
Need support or want to give some feedback? You can click `support` in the [dashboard](http://dashboard.mintlify.com) (bottom left corner) or reach out to [[email protected]](mailto:[email protected]).
152
240
153
-
You can also join our [community](https://mintlify.com/community) to engage with other Mintlify users and stay up to date with the latest feature drops.
241
+
Need more help? Join our Community Discord or contact our Support Team.
0 commit comments