Skip to content

Commit 2a5e451

Browse files
mintlify[bot]mintlify[bot]
authored
Documentation edits made through Mintlify web editor
1 parent 287b00b commit 2a5e451

File tree

6 files changed

+523
-1771
lines changed

6 files changed

+523
-1771
lines changed

‎api-playground/overview.mdx‎

Lines changed: 61 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,68 @@
11
---
2-
title: 'Playground'
3-
description: 'Enable users to interact with your API'
2+
title: 'API Playground'
3+
description: 'Try out API endpoints directly in your documentation'
44
openapi: 'GET /plants/{id}'
55
hideApiMarker: true
66
icon: 'play'
77
---
88

9-
The API playground is an interactive environment to make requests and preview an API endpoint.
9+
The API Playground lets you test API endpoints right from your documentation. Think of it as a built-in API testing tool - no need to switch to Postman or other external tools!
1010

11-
<Info>
12-
Autogenerating API pages with OpenAPI will automatically generate API
13-
playground. Read more about using OpenAPI [here](/api-playground/openapi).
14-
</Info>
11+
## What Can You Do in the Playground?
12+
13+
<CardGroup cols={2}>
14+
<Card title="Test Endpoints" icon="vial">
15+
Make real API calls and see responses instantly
16+
</Card>
17+
<Card title="Fill Parameters" icon="sliders">
18+
Input your own values for path, query, and body parameters
19+
</Card>
20+
<Card title="Authenticate" icon="key">
21+
Add your API keys and authentication tokens
22+
</Card>
23+
<Card title="View Responses" icon="code">
24+
See formatted API responses with syntax highlighting
25+
</Card>
26+
</CardGroup>
27+
28+
## Getting Started
29+
30+
The playground appears automatically on API documentation pages. Here's what you'll typically see:
31+
32+
1. **Authentication Fields** - Where you enter API keys or tokens
33+
2. **Parameter Inputs** - Fields to enter your request data
34+
3. **Try It Button** - Click to make the API call
35+
4. **Response Section** - Shows the API response after your call
36+
37+
<Note>
38+
If you're using OpenAPI to document your API, the playground will be generated automatically!
39+
Learn more about OpenAPI setup [here](/api-playground/openapi).
40+
</Note>
41+
42+
## Example Playground
43+
44+
Here's a simple example of what the playground looks like in action:
45+
46+
<Frame>
47+
![API Playground Example](/images/api-playground-example.png)
48+
</Frame>
49+
50+
## Tips for Using the Playground
51+
52+
<AccordionGroup>
53+
<Accordion title="Save Time with Default Values" icon="clock">
54+
The playground will pre-fill example values from your OpenAPI spec, making it faster to test endpoints.
55+
</Accordion>
56+
57+
<Accordion title="Test Different Scenarios" icon="flask">
58+
Try various parameter combinations to see how the API responds in different situations.
59+
</Accordion>
60+
61+
<Accordion title="Check Error Responses" icon="bug">
62+
Intentionally send invalid data to see how error responses look and understand error handling.
63+
</Accordion>
64+
</AccordionGroup>
65+
66+
<Tip>
67+
Keep your API keys handy! You'll need them to make authenticated requests in the playground.
68+
</Tip>

‎development.mdx‎

Lines changed: 94 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,158 @@
11
---
22
title: "Local Development"
3-
description: "Preview changes locally to update your docs"
3+
description: "Step-by-step guide to preview and test your documentation locally"
44
---
55

6-
<Info>
7-
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
8-
</Info>
6+
<Note>
7+
Before you begin, make sure you have Node.js version 19 or higher installed on your computer. You can check your Node.js version by running `node --version` in your terminal.
8+
</Note>
99

10-
**Step 1**: Install the Mintlify CLI:
10+
## Setting Up Your Environment
1111

12-
<CodeGroup>
12+
### Installing the CLI Tool
13+
14+
First, you'll need to install the Mintlify command-line interface (CLI). Choose one of these commands based on your package manager:
1315

16+
<CodeGroup>
1417
```bash npm
1518
npm i -g mintlify
1619
```
1720

18-
1921
```bash yarn
2022
yarn global add mintlify
2123
```
2224

23-
2425
```bash pnpm
2526
pnpm add -g mintlify
2627
```
27-
2828
</CodeGroup>
2929

30-
**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
30+
### Running the Development Server
3131

32-
```bash
33-
mintlify dev
34-
```
32+
Once installed, follow these steps:
3533

36-
Alternatively, if you do not want to install the CLI globally you can use a run script available:
34+
<Steps>
35+
<Step title="Navigate to Your Docs">
36+
Open your terminal and go to your documentation directory (where your `docs.json` file is located).
37+
</Step>
38+
39+
<Step title="Start the Preview">
40+
Run this command to start your local development server:
41+
```bash
42+
mintlify dev
43+
```
44+
</Step>
3745

38-
<CodeGroup>
46+
<Step title="View Your Docs">
47+
Open your browser and visit `http://localhost:3000` to see your documentation.
48+
</Step>
49+
</Steps>
3950

40-
```bash npm
41-
npx mintlify dev
42-
```
51+
<Tip>
52+
Don't want to install the CLI globally? You can use these run commands instead:
4353

54+
<CodeGroup>
55+
```bash npm
56+
npx mintlify dev
57+
```
4458

45-
```bash yarn
46-
yarn dlx mintlify dev
47-
```
48-
49-
50-
```bash pnpm
51-
pnpm dlx mintlify dev
52-
```
59+
```bash yarn
60+
yarn dlx mintlify dev
61+
```
5362

54-
</CodeGroup>
55-
56-
<Warning>
57-
Yarn's "dlx" run script requires yarn version \>2. See [here](https://yarnpkg.com/cli/dlx) for more information.
58-
</Warning>
63+
```bash pnpm
64+
pnpm dlx mintlify dev
65+
```
66+
</CodeGroup>
67+
</Tip>
5968

60-
A local preview of your documentation will be available at `http://localhost:3000`.
69+
## Common Tasks
6170

62-
### Custom Ports
71+
### Using a Different Port
6372

64-
By default, Mintlify uses port 3000. You can customize the port using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
73+
Need to run on a different port? Use the `--port` flag:
6574

6675
```bash
6776
mintlify dev --port 3333
6877
```
6978

70-
If you attempt to run on a port that's already in use, it will use the next available port:
79+
<Info>
80+
If the port you specify is already in use, Mintlify will automatically try the next available port.
81+
</Info>
82+
83+
### Checking for Broken Links
84+
85+
Keep your documentation reliable by checking for broken links:
7186

72-
```md
73-
Port 3000 is already in use. Trying 3001 instead.
87+
```bash
88+
mintlify broken-links
7489
```
7590

76-
## Versions
91+
### Updating Your CLI Version
7792

78-
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:
93+
To ensure you're using the latest features, regularly update your CLI:
7994

8095
<CodeGroup>
81-
8296
```bash npm
8397
npm i -g mintlify@latest
8498
```
8599

86-
87100
```bash yarn
88101
yarn global upgrade mintlify
89102
```
90103

91-
92104
```bash pnpm
93105
pnpm up --global mintlify
94106
```
95-
96107
</CodeGroup>
97108

98-
## Validating Links
109+
## Best Practices
99110

100-
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
111+
### Code Formatting
112+
For the best writing experience, we recommend:
101113

102-
```bash
103-
mintlify broken-links
104-
```
114+
<CardGroup cols={2}>
115+
<Card title="MDX Extension" icon="brackets-curly">
116+
Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting
117+
</Card>
118+
<Card title="Prettier" icon="wand-magic-sparkles">
119+
Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to automatically format your documentation
120+
</Card>
121+
</CardGroup>
122+
123+
## Troubleshooting Guide
124+
125+
<AccordionGroup>
126+
<Accordion title="Development server won't start" icon="circle-exclamation">
127+
Try these steps in order:
128+
1. Check your Node.js version (`node --version`)
129+
2. Delete the `~/.mintlify` folder
130+
3. Reinstall the CLI: `npm remove -g mintlify && npm install -g mintlify`
131+
</Accordion>
132+
133+
<Accordion title='Error: "sharp" module not loading' icon="wrench">
134+
This usually means you need to update Node.js:
135+
1. Remove Mintlify: `npm remove -g mintlify`
136+
2. Update to Node.js v19 or higher
137+
3. Reinstall: `npm install -g mintlify`
138+
</Accordion>
139+
140+
<Accordion title="Changes not showing up" icon="rotate">
141+
Try these solutions:
142+
1. Clear your browser cache
143+
2. Restart the development server
144+
3. Check for syntax errors in your MDX files
145+
</Accordion>
146+
</AccordionGroup>
105147

106-
## Deployment
148+
## Deployment Status
107149

108-
If the deployment is successful, you should see the following:
150+
When your deployment succeeds, you'll see green checkmarks in your GitHub status:
109151

110152
<Frame>
111153
<img
112154
className="rounded-md"
113155
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
156+
alt="Successful deployment status showing green checkmarks"
114157
/>
115-
</Frame>
116-
117-
## Code Formatting
118-
119-
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.
120-
121-
## Troubleshooting
122-
123-
<AccordionGroup>
124-
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
125-
This may be due to an outdated version of node. Try the following:
126-
127-
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
128-
2. Upgrade to Node v19 or higher.
129-
3. Reinstall mintlify: `npm install -g mintlify`
130-
</Accordion>
131-
<Accordion title="Issue: Encountering an unknown error">
132-
Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run `mintlify dev` again.
133-
</Accordion>
134-
</AccordionGroup>
158+
</Frame>

‎docs.json‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,12 @@
2222
{
2323
"group": "Editing",
2424
"icon": "pen-paintbrush",
25-
"pages": ["development", "web-editor"]
25+
"pages": [
26+
"development",
27+
"web-editor",
28+
"quickstart",
29+
"development"
30+
]
2631
},
2732
"settings/global",
2833
{
@@ -37,7 +42,9 @@
3742
]
3843
},
3944
"themes",
40-
"migration"
45+
"migration",
46+
"text",
47+
"settings/global"
4148
]
4249
},
4350
{
@@ -72,7 +79,8 @@
7279
"api-playground/mdx/authentication"
7380
]
7481
},
75-
"api-playground/troubleshooting"
82+
"api-playground/troubleshooting",
83+
"api-playground/overview"
7684
]
7785
},
7886
{
@@ -262,7 +270,9 @@
262270
"groups": [
263271
{
264272
"group": "Changelog",
265-
"pages": ["changelog/overview"]
273+
"pages": [
274+
"changelog/overview"
275+
]
266276
}
267277
]
268278
}
@@ -374,4 +384,4 @@
374384
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
375385
}
376386
}
377-
}
387+
}

0 commit comments

Comments
 (0)