Skip to content

Commit fb72506

Browse files
apronkinapronkin
authored
Initial commit
0 parents  commit fb72506

23 files changed

+1779
-0
lines changed

‎README.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Mintlify Starter Kit
2+
3+
Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including
4+
5+
- Guide pages
6+
- Navigation
7+
- Customizations
8+
- API Reference pages
9+
- Use of popular components
10+
11+
### Development
12+
13+
Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
14+
15+
```
16+
npm i -g mintlify
17+
```
18+
19+
Run the following command at the root of your documentation (where mint.json is)
20+
21+
```
22+
mintlify dev
23+
```
24+
25+
### Publishing Changes
26+
27+
Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.
28+
29+
#### Troubleshooting
30+
31+
- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
32+
- Page loads as a 404 - Make sure you are running in a folder with `mint.json`

‎api-reference/endpoint/create.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: 'Create Plant'
3+
openapi: 'POST /plants'
4+
---

‎api-reference/endpoint/delete.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: 'Delete Plant'
3+
openapi: 'DELETE /plants/{id}'
4+
---

‎api-reference/endpoint/get.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: 'Get Plants'
3+
openapi: 'GET /plants'
4+
---

‎api-reference/introduction.mdx

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: 'Introduction'
3+
description: 'Example section for showcasing API endpoints'
4+
---
5+
6+
<Note>
7+
If you're not looking to build API reference documentation, you can delete
8+
this section by removing the api-reference folder.
9+
</Note>
10+
11+
## Welcome
12+
13+
There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.
14+
15+
<Card
16+
title="Plant Store Endpoints"
17+
icon="leaf"
18+
href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json"
19+
>
20+
View the OpenAPI specification file
21+
</Card>
22+
23+
## Authentication
24+
25+
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
26+
27+
```json
28+
"security": [
29+
{
30+
"bearerAuth": []
31+
}
32+
]
33+
```

‎api-reference/openapi.json

+195
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
{
2+
"openapi": "3.0.1",
3+
"info": {
4+
"title": "OpenAPI Plant Store",
5+
"description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
6+
"license": {
7+
"name": "MIT"
8+
},
9+
"version": "1.0.0"
10+
},
11+
"servers": [
12+
{
13+
"url": "http://sandbox.mintlify.com"
14+
}
15+
],
16+
"security": [
17+
{
18+
"bearerAuth": []
19+
}
20+
],
21+
"paths": {
22+
"/plants": {
23+
"get": {
24+
"description": "Returns all plants from the system that the user has access to",
25+
"parameters": [
26+
{
27+
"name": "limit",
28+
"in": "query",
29+
"description": "The maximum number of results to return",
30+
"schema": {
31+
"type": "integer",
32+
"format": "int32"
33+
}
34+
}
35+
],
36+
"responses": {
37+
"200": {
38+
"description": "Plant response",
39+
"content": {
40+
"application/json": {
41+
"schema": {
42+
"type": "array",
43+
"items": {
44+
"$ref": "#/components/schemas/Plant"
45+
}
46+
}
47+
}
48+
}
49+
},
50+
"400": {
51+
"description": "Unexpected error",
52+
"content": {
53+
"application/json": {
54+
"schema": {
55+
"$ref": "#/components/schemas/Error"
56+
}
57+
}
58+
}
59+
}
60+
}
61+
},
62+
"post": {
63+
"description": "Creates a new plant in the store",
64+
"requestBody": {
65+
"description": "Plant to add to the store",
66+
"content": {
67+
"application/json": {
68+
"schema": {
69+
"$ref": "#/components/schemas/NewPlant"
70+
}
71+
}
72+
},
73+
"required": true
74+
},
75+
"responses": {
76+
"200": {
77+
"description": "plant response",
78+
"content": {
79+
"application/json": {
80+
"schema": {
81+
"$ref": "#/components/schemas/Plant"
82+
}
83+
}
84+
}
85+
},
86+
"400": {
87+
"description": "unexpected error",
88+
"content": {
89+
"application/json": {
90+
"schema": {
91+
"$ref": "#/components/schemas/Error"
92+
}
93+
}
94+
}
95+
}
96+
}
97+
}
98+
},
99+
"/plants/{id}": {
100+
"delete": {
101+
"description": "Deletes a single plant based on the ID supplied",
102+
"parameters": [
103+
{
104+
"name": "id",
105+
"in": "path",
106+
"description": "ID of plant to delete",
107+
"required": true,
108+
"schema": {
109+
"type": "integer",
110+
"format": "int64"
111+
}
112+
}
113+
],
114+
"responses": {
115+
"204": {
116+
"description": "Plant deleted",
117+
"content": {}
118+
},
119+
"400": {
120+
"description": "unexpected error",
121+
"content": {
122+
"application/json": {
123+
"schema": {
124+
"$ref": "#/components/schemas/Error"
125+
}
126+
}
127+
}
128+
}
129+
}
130+
}
131+
}
132+
},
133+
"components": {
134+
"schemas": {
135+
"Plant": {
136+
"required": [
137+
"name"
138+
],
139+
"type": "object",
140+
"properties": {
141+
"name": {
142+
"description": "The name of the plant",
143+
"type": "string"
144+
},
145+
"tag": {
146+
"description": "Tag to specify the type",
147+
"type": "string"
148+
}
149+
}
150+
},
151+
"NewPlant": {
152+
"allOf": [
153+
{
154+
"$ref": "#/components/schemas/Plant"
155+
},
156+
{
157+
"required": [
158+
"id"
159+
],
160+
"type": "object",
161+
"properties": {
162+
"id": {
163+
"description": "Identification number of the plant",
164+
"type": "integer",
165+
"format": "int64"
166+
}
167+
}
168+
}
169+
]
170+
},
171+
"Error": {
172+
"required": [
173+
"error",
174+
"message"
175+
],
176+
"type": "object",
177+
"properties": {
178+
"error": {
179+
"type": "integer",
180+
"format": "int32"
181+
},
182+
"message": {
183+
"type": "string"
184+
}
185+
}
186+
}
187+
},
188+
"securitySchemes": {
189+
"bearerAuth": {
190+
"type": "http",
191+
"scheme": "bearer"
192+
}
193+
}
194+
}
195+
}

‎development.mdx

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: 'Development'
3+
description: 'Preview changes locally to update your docs'
4+
---
5+
6+
<Info>
7+
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
8+
</Info>
9+
10+
Follow these steps to install and run Mintlify on your operating system:
11+
12+
**Step 1**: Install Mintlify:
13+
14+
<CodeGroup>
15+
16+
```bash npm
17+
npm i -g mintlify
18+
```
19+
20+
```bash yarn
21+
yarn global add mintlify
22+
```
23+
24+
</CodeGroup>
25+
26+
**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
27+
28+
```bash
29+
mintlify dev
30+
```
31+
32+
A local preview of your documentation will be available at `http://localhost:3000`.
33+
34+
### Custom Ports
35+
36+
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
37+
38+
```bash
39+
mintlify dev --port 3333
40+
```
41+
42+
If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
43+
44+
```md
45+
Port 3000 is already in use. Trying 3001 instead.
46+
```
47+
48+
## Mintlify Versions
49+
50+
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
51+
52+
<CodeGroup>
53+
54+
```bash npm
55+
npm i -g mintlify@latest
56+
```
57+
58+
```bash yarn
59+
yarn global upgrade mintlify
60+
```
61+
62+
</CodeGroup>
63+
64+
## Validating Links
65+
66+
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
67+
68+
```bash
69+
mintlify broken-links
70+
```
71+
72+
## Deployment
73+
74+
<Tip>
75+
Unlimited editors available under the [Pro
76+
Plan](https://mintlify.com/pricing) and above.
77+
</Tip>
78+
79+
If the deployment is successful, you should see the following:
80+
81+
<Frame>
82+
<img src="/images/checks-passed.png" style={{ borderRadius: '0.5rem' }} />
83+
</Frame>
84+
85+
## Code Formatting
86+
87+
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
88+
89+
## Troubleshooting
90+
91+
<AccordionGroup>
92+
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
93+
94+
This may be due to an outdated version of node. Try the following:
95+
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
96+
2. Upgrade to Node v19 or higher.
97+
3. Reinstall mintlify: `npm install -g mintlify`
98+
</Accordion>
99+
100+
<Accordion title="Issue: Encountering an unknown error">
101+
102+
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
103+
</Accordion>
104+
</AccordionGroup>
105+
106+
Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions)

0 commit comments

Comments
 (0)