Skip to content

Commit 4ebf8d7

Browse files
lalit-swanlalit-swan
authoredJan 26, 2025
Initial commit
0 parents  commit 4ebf8d7

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)

‎essentials/code.mdx

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: 'Code Blocks'
3+
description: 'Display inline code and code blocks'
4+
icon: 'code'
5+
---
6+
7+
## Basic
8+
9+
### Inline Code
10+
11+
To denote a `word` or `phrase` as code, enclose it in backticks (`).
12+
13+
```
14+
To denote a `word` or `phrase` as code, enclose it in backticks (`).
15+
```
16+
17+
### Code Block
18+
19+
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
20+
21+
```java HelloWorld.java
22+
class HelloWorld {
23+
public static void main(String[] args) {
24+
System.out.println("Hello, World!");
25+
}
26+
}
27+
```
28+
29+
````md
30+
```java HelloWorld.java
31+
class HelloWorld {
32+
public static void main(String[] args) {
33+
System.out.println("Hello, World!");
34+
}
35+
}
36+
```
37+
````

‎essentials/images.mdx

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: 'Images and Embeds'
3+
description: 'Add image, video, and other HTML elements'
4+
icon: 'image'
5+
---
6+
7+
<img
8+
style={{ borderRadius: '0.5rem' }}
9+
src="https://mintlify-assets.b-cdn.net/bigbend.jpg"
10+
/>
11+
12+
## Image
13+
14+
### Using Markdown
15+
16+
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
17+
18+
```md
19+
![title](/path/image.jpg)
20+
```
21+
22+
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
23+
24+
### Using Embeds
25+
26+
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
27+
28+
```html
29+
<img height="200" src="/path/image.jpg" />
30+
```
31+
32+
## Embeds and HTML elements
33+
34+
<iframe
35+
width="560"
36+
height="315"
37+
src="https://www.youtube.com/embed/4KzFe50RQkQ"
38+
title="YouTube video player"
39+
frameBorder="0"
40+
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
41+
allowFullScreen
42+
style={{ width: '100%', borderRadius: '0.5rem' }}
43+
></iframe>
44+
45+
<br />
46+
47+
<Tip>
48+
49+
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
50+
51+
</Tip>
52+
53+
### iFrames
54+
55+
Loads another HTML page within the document. Most commonly used for embedding videos.
56+
57+
```html
58+
<iframe src="https://www.youtube.com/embed/4KzFe50RQkQ"> </iframe>
59+
```

‎essentials/markdown.mdx

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: 'Markdown Syntax'
3+
description: 'Text, title, and styling in standard markdown'
4+
icon: 'text-size'
5+
---
6+
7+
## Titles
8+
9+
Best used for section headers.
10+
11+
```md
12+
## Titles
13+
```
14+
15+
### Subtitles
16+
17+
Best use to subsection headers.
18+
19+
```md
20+
### Subtitles
21+
```
22+
23+
<Tip>
24+
25+
Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
26+
27+
</Tip>
28+
29+
## Text Formatting
30+
31+
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
32+
33+
| Style | How to write it | Result |
34+
| ------------- | ----------------- | --------------- |
35+
| Bold | `**bold**` | **bold** |
36+
| Italic | `_italic_` | _italic_ |
37+
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
38+
39+
You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
40+
41+
You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.
42+
43+
| Text Size | How to write it | Result |
44+
| ----------- | ------------------------ | ---------------------- |
45+
| Superscript | `<sup>superscript</sup>` | <sup>superscript</sup> |
46+
| Subscript | `<sub>subscript</sub>` | <sub>subscript</sub> |
47+
48+
## Linking to Pages
49+
50+
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
51+
52+
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
53+
54+
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
55+
56+
## Blockquotes
57+
58+
### Singleline
59+
60+
To create a blockquote, add a `>` in front of a paragraph.
61+
62+
> Dorothy followed her through many of the beautiful rooms in her castle.
63+
64+
```md
65+
> Dorothy followed her through many of the beautiful rooms in her castle.
66+
```
67+
68+
### Multiline
69+
70+
> Dorothy followed her through many of the beautiful rooms in her castle.
71+
>
72+
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
73+
74+
```md
75+
> Dorothy followed her through many of the beautiful rooms in her castle.
76+
>
77+
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
78+
```
79+
80+
### LaTeX
81+
82+
Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
83+
84+
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>
85+
86+
```md
87+
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>
88+
```

‎essentials/navigation.mdx

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: 'Navigation'
3+
description: 'The navigation field in mint.json defines the pages that go in the navigation menu'
4+
icon: 'map'
5+
---
6+
7+
The navigation menu is the list of links on every website.
8+
9+
You will likely update `mint.json` every time you add a new page. Pages do not show up automatically.
10+
11+
## Navigation syntax
12+
13+
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
14+
15+
<CodeGroup>
16+
17+
```json Regular Navigation
18+
"navigation": [
19+
{
20+
"group": "Getting Started",
21+
"pages": ["quickstart"]
22+
}
23+
]
24+
```
25+
26+
```json Nested Navigation
27+
"navigation": [
28+
{
29+
"group": "Getting Started",
30+
"pages": [
31+
"quickstart",
32+
{
33+
"group": "Nested Reference Pages",
34+
"pages": ["nested-reference-page"]
35+
}
36+
]
37+
}
38+
]
39+
```
40+
41+
</CodeGroup>
42+
43+
## Folders
44+
45+
Simply put your MDX files in folders and update the paths in `mint.json`.
46+
47+
For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
48+
49+
<Warning>
50+
51+
You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
52+
53+
</Warning>
54+
55+
```json Navigation With Folder
56+
"navigation": [
57+
{
58+
"group": "Group Name",
59+
"pages": ["your-folder/your-page"]
60+
}
61+
]
62+
```
63+
64+
## Hidden Pages
65+
66+
MDX files not included in `mint.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.

‎essentials/reusable-snippets.mdx

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Reusable Snippets
3+
description: Reusable, custom snippets to keep content in sync
4+
icon: 'recycle'
5+
---
6+
7+
import SnippetIntro from '/snippets/snippet-intro.mdx';
8+
9+
<SnippetIntro />
10+
11+
## Creating a custom snippet
12+
13+
**Pre-condition**: You must create your snippet file in the `snippets` directory.
14+
15+
<Note>
16+
Any page in the `snippets` directory will be treated as a snippet and will not
17+
be rendered into a standalone page. If you want to create a standalone page
18+
from the snippet, import the snippet into another file and call it as a
19+
component.
20+
</Note>
21+
22+
### Default export
23+
24+
1. Add content to your snippet file that you want to re-use across multiple
25+
locations. Optionally, you can add variables that can be filled in via props
26+
when you import the snippet.
27+
28+
```mdx snippets/my-snippet.mdx
29+
Hello world! This is my content I want to reuse across pages. My keyword of the
30+
day is {word}.
31+
```
32+
33+
<Warning>
34+
The content that you want to reuse must be inside the `snippets` directory in
35+
order for the import to work.
36+
</Warning>
37+
38+
2. Import the snippet into your destination file.
39+
40+
```mdx destination-file.mdx
41+
---
42+
title: My title
43+
description: My Description
44+
---
45+
46+
import MySnippet from '/snippets/path/to/my-snippet.mdx';
47+
48+
## Header
49+
50+
Lorem impsum dolor sit amet.
51+
52+
<MySnippet word="bananas" />
53+
```
54+
55+
### Reusable variables
56+
57+
1. Export a variable from your snippet file:
58+
59+
```mdx snippets/path/to/custom-variables.mdx
60+
export const myName = 'my name';
61+
62+
export const myObject = { fruit: 'strawberries' };
63+
```
64+
65+
2. Import the snippet from your destination file and use the variable:
66+
67+
```mdx destination-file.mdx
68+
---
69+
title: My title
70+
description: My Description
71+
---
72+
73+
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
74+
75+
Hello, my name is {myName} and I like {myObject.fruit}.
76+
```
77+
78+
### Reusable components
79+
80+
1. Inside your snippet file, create a component that takes in props by exporting
81+
your component in the form of an arrow function.
82+
83+
```mdx snippets/custom-component.mdx
84+
export const MyComponent = ({ title }) => (
85+
<div>
86+
<h1>{title}</h1>
87+
<p>... snippet content ...</p>
88+
</div>
89+
);
90+
```
91+
92+
<Warning>
93+
MDX does not compile inside the body of an arrow function. Stick to HTML
94+
syntax when you can or use a default export if you need to use MDX.
95+
</Warning>
96+
97+
2. Import the snippet into your destination file and pass in the props
98+
99+
```mdx destination-file.mdx
100+
---
101+
title: My title
102+
description: My Description
103+
---
104+
105+
import { MyComponent } from '/snippets/custom-component.mdx';
106+
107+
Lorem ipsum dolor sit amet.
108+
109+
<MyComponent title={'Custom title'} />
110+
```

‎essentials/settings.mdx

+318
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
---
2+
title: 'Global Settings'
3+
description: 'Mintlify gives you complete control over the look and feel of your documentation using the mint.json file'
4+
icon: 'gear'
5+
---
6+
7+
Every Mintlify site needs a `mint.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
8+
9+
## Properties
10+
11+
<ResponseField name="name" type="string" required>
12+
Name of your project. Used for the global title.
13+
14+
Example: `mintlify`
15+
16+
</ResponseField>
17+
18+
<ResponseField name="navigation" type="Navigation[]" required>
19+
An array of groups with all the pages within that group
20+
<Expandable title="Navigation">
21+
<ResponseField name="group" type="string">
22+
The name of the group.
23+
24+
Example: `Settings`
25+
26+
</ResponseField>
27+
<ResponseField name="pages" type="string[]">
28+
The relative paths to the markdown files that will serve as pages.
29+
30+
Example: `["customization", "page"]`
31+
32+
</ResponseField>
33+
34+
</Expandable>
35+
</ResponseField>
36+
37+
<ResponseField name="logo" type="string or object">
38+
Path to logo image or object with path to "light" and "dark" mode logo images
39+
<Expandable title="Logo">
40+
<ResponseField name="light" type="string">
41+
Path to the logo in light mode
42+
</ResponseField>
43+
<ResponseField name="dark" type="string">
44+
Path to the logo in dark mode
45+
</ResponseField>
46+
<ResponseField name="href" type="string" default="/">
47+
Where clicking on the logo links you to
48+
</ResponseField>
49+
</Expandable>
50+
</ResponseField>
51+
52+
<ResponseField name="favicon" type="string">
53+
Path to the favicon image
54+
</ResponseField>
55+
56+
<ResponseField name="colors" type="Colors">
57+
Hex color codes for your global theme
58+
<Expandable title="Colors">
59+
<ResponseField name="primary" type="string" required>
60+
The primary color. Used for most often for highlighted content, section
61+
headers, accents, in light mode
62+
</ResponseField>
63+
<ResponseField name="light" type="string">
64+
The primary color for dark mode. Used for most often for highlighted
65+
content, section headers, accents, in dark mode
66+
</ResponseField>
67+
<ResponseField name="dark" type="string">
68+
The primary color for important buttons
69+
</ResponseField>
70+
<ResponseField name="background" type="object">
71+
The color of the background in both light and dark mode
72+
<Expandable title="Object">
73+
<ResponseField name="light" type="string" required>
74+
The hex color code of the background in light mode
75+
</ResponseField>
76+
<ResponseField name="dark" type="string" required>
77+
The hex color code of the background in dark mode
78+
</ResponseField>
79+
</Expandable>
80+
</ResponseField>
81+
</Expandable>
82+
</ResponseField>
83+
84+
<ResponseField name="topbarLinks" type="TopbarLink[]">
85+
Array of `name`s and `url`s of links you want to include in the topbar
86+
<Expandable title="TopbarLink">
87+
<ResponseField name="name" type="string">
88+
The name of the button.
89+
90+
Example: `Contact us`
91+
</ResponseField>
92+
<ResponseField name="url" type="string">
93+
The url once you click on the button. Example: `https://mintlify.com/docs`
94+
</ResponseField>
95+
96+
</Expandable>
97+
</ResponseField>
98+
99+
<ResponseField name="topbarCtaButton" type="Call to Action">
100+
<Expandable title="Topbar Call to Action">
101+
<ResponseField name="type" type={'"link" or "github"'} default="link">
102+
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
103+
</ResponseField>
104+
<ResponseField name="url" type="string">
105+
If `link`: What the button links to.
106+
107+
If `github`: Link to the repository to load GitHub information from.
108+
</ResponseField>
109+
<ResponseField name="name" type="string">
110+
Text inside the button. Only required if `type` is a `link`.
111+
</ResponseField>
112+
113+
</Expandable>
114+
</ResponseField>
115+
116+
<ResponseField name="versions" type="string[]">
117+
Array of version names. Only use this if you want to show different versions
118+
of docs with a dropdown in the navigation bar.
119+
</ResponseField>
120+
121+
<ResponseField name="anchors" type="Anchor[]">
122+
An array of the anchors, includes the `icon`, `color`, and `url`.
123+
<Expandable title="Anchor">
124+
<ResponseField name="icon" type="string">
125+
The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
126+
127+
Example: `comments`
128+
</ResponseField>
129+
<ResponseField name="name" type="string">
130+
The name of the anchor label.
131+
132+
Example: `Community`
133+
</ResponseField>
134+
<ResponseField name="url" type="string">
135+
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
136+
</ResponseField>
137+
<ResponseField name="color" type="string">
138+
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
139+
</ResponseField>
140+
<ResponseField name="version" type="string">
141+
Used if you want to hide an anchor until the correct docs version is selected.
142+
</ResponseField>
143+
<ResponseField name="isDefaultHidden" type="boolean" default="false">
144+
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
145+
</ResponseField>
146+
<ResponseField name="iconType" default="duotone" type="string">
147+
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
148+
</ResponseField>
149+
150+
</Expandable>
151+
</ResponseField>
152+
153+
<ResponseField name="topAnchor" type="Object">
154+
Override the default configurations for the top-most anchor.
155+
<Expandable title="Object">
156+
<ResponseField name="name" default="Documentation" type="string">
157+
The name of the top-most anchor
158+
</ResponseField>
159+
<ResponseField name="icon" default="book-open" type="string">
160+
Font Awesome icon.
161+
</ResponseField>
162+
<ResponseField name="iconType" default="duotone" type="string">
163+
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
164+
</ResponseField>
165+
</Expandable>
166+
</ResponseField>
167+
168+
<ResponseField name="tabs" type="Tabs[]">
169+
An array of navigational tabs.
170+
<Expandable title="Tabs">
171+
<ResponseField name="name" type="string">
172+
The name of the tab label.
173+
</ResponseField>
174+
<ResponseField name="url" type="string">
175+
The start of the URL that marks what pages go in the tab. Generally, this
176+
is the name of the folder you put your pages in.
177+
</ResponseField>
178+
</Expandable>
179+
</ResponseField>
180+
181+
<ResponseField name="api" type="API">
182+
Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
183+
<Expandable title="API">
184+
<ResponseField name="baseUrl" type="string">
185+
The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
186+
options that the user can toggle.
187+
</ResponseField>
188+
189+
<ResponseField name="auth" type="Auth">
190+
<Expandable title="Auth">
191+
<ResponseField name="method" type='"bearer" | "basic" | "key"'>
192+
The authentication strategy used for all API endpoints.
193+
</ResponseField>
194+
<ResponseField name="name" type="string">
195+
The name of the authentication parameter used in the API playground.
196+
197+
If method is `basic`, the format should be `[usernameName]:[passwordName]`
198+
</ResponseField>
199+
<ResponseField name="inputPrefix" type="string">
200+
The default value that's designed to be a prefix for the authentication input field.
201+
202+
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
203+
</ResponseField>
204+
</Expandable>
205+
</ResponseField>
206+
207+
<ResponseField name="playground" type="Playground">
208+
Configurations for the API playground
209+
210+
<Expandable title="Playground">
211+
<ResponseField name="mode" default="show" type='"show" | "simple" | "hide"'>
212+
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
213+
214+
Learn more at the [playground guides](/api-playground/demo)
215+
</ResponseField>
216+
</Expandable>
217+
</ResponseField>
218+
219+
<ResponseField name="maintainOrder" type="boolean">
220+
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
221+
222+
<Warning>This behavior will soon be enabled by default, at which point this field will be deprecated.</Warning>
223+
</ResponseField>
224+
225+
</Expandable>
226+
</ResponseField>
227+
228+
<ResponseField name="openapi" type="string | string[]">
229+
A string or an array of strings of URL(s) or relative path(s) pointing to your
230+
OpenAPI file.
231+
232+
Examples:
233+
<CodeGroup>
234+
```json Absolute
235+
"openapi": "https://example.com/openapi.json"
236+
```
237+
```json Relative
238+
"openapi": "/openapi.json"
239+
```
240+
```json Multiple
241+
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
242+
```
243+
</CodeGroup>
244+
245+
</ResponseField>
246+
247+
<ResponseField name="footerSocials" type="FooterSocials">
248+
An object of social media accounts where the key:property pair represents the social media platform and the account url.
249+
250+
Example:
251+
```json
252+
{
253+
"x": "https://x.com/mintlify",
254+
"website": "https://mintlify.com"
255+
}
256+
```
257+
<Expandable title="FooterSocials">
258+
<ResponseField name="[key]" type="string">
259+
One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
260+
261+
Example: `x`
262+
</ResponseField>
263+
<ResponseField name="property" type="string">
264+
The URL to the social platform.
265+
266+
Example: `https://x.com/mintlify`
267+
</ResponseField>
268+
</Expandable>
269+
</ResponseField>
270+
271+
<ResponseField name="feedback" type="Feedback">
272+
Configurations to enable feedback buttons
273+
274+
<Expandable title="Feedback">
275+
<ResponseField name="suggestEdit" type="boolean" default="false">
276+
Enables a button to allow users to suggest edits via pull requests
277+
</ResponseField>
278+
<ResponseField name="raiseIssue" type="boolean" default="false">
279+
Enables a button to allow users to raise an issue about the documentation
280+
</ResponseField>
281+
</Expandable>
282+
</ResponseField>
283+
284+
<ResponseField name="modeToggle" type="ModeToggle">
285+
Customize the dark mode toggle.
286+
<Expandable title="ModeToggle">
287+
<ResponseField name="default" type={'"light" or "dark"'}>
288+
Set if you always want to show light or dark mode for new users. When not
289+
set, we default to the same mode as the user's operating system.
290+
</ResponseField>
291+
<ResponseField name="isHidden" type="boolean" default="false">
292+
Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
293+
294+
<CodeGroup>
295+
```json Only Dark Mode
296+
"modeToggle": {
297+
"default": "dark",
298+
"isHidden": true
299+
}
300+
```
301+
302+
```json Only Light Mode
303+
"modeToggle": {
304+
"default": "light",
305+
"isHidden": true
306+
}
307+
```
308+
</CodeGroup>
309+
310+
</ResponseField>
311+
312+
</Expandable>
313+
</ResponseField>
314+
315+
<ResponseField name="backgroundImage" type="string">
316+
A background image to be displayed behind every page. See example with
317+
[Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
318+
</ResponseField>

‎favicon.svg

+49
Loading

‎images/checks-passed.png

157 KB
Loading

‎images/hero-dark.svg

+161
Loading

‎images/hero-light.svg

+155
Loading

‎introduction.mdx

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Introduction
3+
description: "Welcome to the home of your new documentation"
4+
---
5+
6+
<img
7+
className="block dark:hidden"
8+
src="/images/hero-light.svg"
9+
alt="Hero Light"
10+
/>
11+
<img
12+
className="hidden dark:block"
13+
src="/images/hero-dark.svg"
14+
alt="Hero Dark"
15+
/>
16+
17+
## Setting up
18+
19+
The first step to world-class documentation is setting up your editing environments.
20+
21+
<CardGroup cols={2}>
22+
<Card
23+
title="Edit Your Docs"
24+
icon="pen-to-square"
25+
href="https://mintlify.com/docs/quickstart"
26+
>
27+
Get your docs set up locally for easy development
28+
</Card>
29+
<Card
30+
title="Preview Changes"
31+
icon="image"
32+
href="https://mintlify.com/docs/development"
33+
>
34+
Preview your changes before you push to make sure they're perfect
35+
</Card>
36+
</CardGroup>
37+
38+
## Make it yours
39+
40+
Update your docs to your brand and add valuable content for the best user conversion.
41+
42+
<CardGroup cols={2}>
43+
<Card
44+
title="Customize Style"
45+
icon="palette"
46+
href="https://mintlify.com/docs/settings/global"
47+
>
48+
Customize your docs to your company's colors and brands
49+
</Card>
50+
<Card
51+
title="Reference APIs"
52+
icon="code"
53+
href="https://mintlify.com/docs/api-playground/openapi"
54+
>
55+
Automatically generate endpoints from an OpenAPI spec
56+
</Card>
57+
<Card
58+
title="Add Components"
59+
icon="screwdriver-wrench"
60+
href="https://mintlify.com/docs/content/components/accordions"
61+
>
62+
Build interactive features and designs to guide your users
63+
</Card>
64+
<Card
65+
title="Get Inspiration"
66+
icon="stars"
67+
href="https://mintlify.com/customers"
68+
>
69+
Check out our showcase of our favorite documentation
70+
</Card>
71+
</CardGroup>

‎logo/dark.svg

+55
Loading

‎logo/light.svg

+51
Loading

‎mint.json

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
{
2+
"$schema": "https://mintlify.com/schema.json",
3+
"name": "Starter Kit",
4+
"logo": {
5+
"dark": "/logo/dark.svg",
6+
"light": "/logo/light.svg"
7+
},
8+
"favicon": "/favicon.svg",
9+
"colors": {
10+
"primary": "#0D9373",
11+
"light": "#07C983",
12+
"dark": "#0D9373",
13+
"anchors": {
14+
"from": "#0D9373",
15+
"to": "#07C983"
16+
}
17+
},
18+
"topbarLinks": [
19+
{
20+
"name": "Support",
21+
"url": "mailto:hi@mintlify.com"
22+
}
23+
],
24+
"topbarCtaButton": {
25+
"name": "Dashboard",
26+
"url": "https://dashboard.mintlify.com"
27+
},
28+
"tabs": [
29+
{
30+
"name": "API Reference",
31+
"url": "api-reference"
32+
}
33+
],
34+
"anchors": [
35+
{
36+
"name": "Documentation",
37+
"icon": "book-open-cover",
38+
"url": "https://mintlify.com/docs"
39+
},
40+
{
41+
"name": "Community",
42+
"icon": "slack",
43+
"url": "https://mintlify.com/community"
44+
},
45+
{
46+
"name": "Blog",
47+
"icon": "newspaper",
48+
"url": "https://mintlify.com/blog"
49+
}
50+
],
51+
"navigation": [
52+
{
53+
"group": "Get Started",
54+
"pages": [
55+
"introduction",
56+
"quickstart",
57+
"development"
58+
]
59+
},
60+
{
61+
"group": "Essentials",
62+
"pages": [
63+
"essentials/markdown",
64+
"essentials/code",
65+
"essentials/images",
66+
"essentials/settings",
67+
"essentials/navigation",
68+
"essentials/reusable-snippets"
69+
]
70+
},
71+
{
72+
"group": "API Documentation",
73+
"pages": [
74+
"api-reference/introduction"
75+
]
76+
},
77+
{
78+
"group": "Endpoint Examples",
79+
"pages": [
80+
"api-reference/endpoint/get",
81+
"api-reference/endpoint/create",
82+
"api-reference/endpoint/delete"
83+
]
84+
}
85+
],
86+
"footerSocials": {
87+
"x": "https://x.com/mintlify",
88+
"github": "https://github.com/mintlify",
89+
"linkedin": "https://linkedin.com/company/mintlify"
90+
}
91+
}

‎quickstart.mdx

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: 'Quickstart'
3+
description: 'Start building awesome documentation in under 5 minutes'
4+
---
5+
6+
## Setup your development
7+
8+
Learn how to update your docs locally and deploy them to the public.
9+
10+
### Edit and preview
11+
12+
<AccordionGroup>
13+
<Accordion icon="github" title="Clone your docs locally">
14+
During the onboarding process, we created a repository on your Github with
15+
your docs content. You can find this repository on our
16+
[dashboard](https://dashboard.mintlify.com). To clone the repository
17+
locally, follow these
18+
[instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
19+
in your terminal.
20+
</Accordion>
21+
<Accordion icon="rectangle-terminal" title="Preview changes">
22+
Previewing helps you make sure your changes look as intended. We built a
23+
command line interface to render these changes locally. 1. Install the
24+
[Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the
25+
documentation changes locally with this command: ``` npm i -g mintlify ```
26+
2. Run the following command at the root of your documentation (where
27+
`mint.json` is): ``` mintlify dev ```
28+
</Accordion>
29+
</AccordionGroup>
30+
31+
### Deploy your changes
32+
33+
<AccordionGroup>
34+
35+
<Accordion icon="message-bot" title="Install our Github app">
36+
Our Github app automatically deploys your changes to your docs site, so you
37+
don't need to manage deployments yourself. You can find the link to install on
38+
your [dashboard](https://dashboard.mintlify.com). Once the bot has been
39+
successfully installed, there should be a check mark next to the commit hash
40+
of the repo.
41+
</Accordion>
42+
<Accordion icon="rocket" title="Push your changes">
43+
[Commit and push your changes to
44+
Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push)
45+
for your changes to update in your docs site. If you push and don't see that
46+
the Github app successfully deployed your changes, you can also manually
47+
update your docs through our [dashboard](https://dashboard.mintlify.com).
48+
</Accordion>
49+
50+
</AccordionGroup>
51+
52+
## Update your docs
53+
54+
Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own.
55+
56+
<CardGroup>
57+
58+
<Card title="Style Your Docs" icon="paintbrush" href="/settings/global">
59+
Add flair to your docs with personalized branding.
60+
</Card>
61+
62+
<Card
63+
title="Add API Endpoints"
64+
icon="square-code"
65+
href="/api-playground/configuration"
66+
>
67+
Implement your OpenAPI spec and enable API user interaction.
68+
</Card>
69+
70+
<Card
71+
title="Integrate Analytics"
72+
icon="chart-mixed"
73+
href="/analytics/supported-integrations"
74+
>
75+
Draw insights from user interactions with your documentation.
76+
</Card>
77+
78+
<Card
79+
title="Host on a Custom Domain"
80+
icon="browser"
81+
href="/settings/custom-domain/subdomain"
82+
>
83+
Keep your docs on your own website's subdomain.
84+
</Card>
85+
86+
</CardGroup>

‎snippets/snippet-intro.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
One of the core principles of software development is DRY (Don't Repeat
2+
Yourself). This is a principle that apply to documentation as
3+
well. If you find yourself repeating the same content in multiple places, you
4+
should consider creating a custom snippet to keep your content in sync.

0 commit comments

Comments
 (0)
Please sign in to comment.