Skip to content

Improve Documentation Readability and Simplify Onboarding Experience #585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Improve Documentation Readability and Simplify Onboarding Experience #585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 61 additions & 7 deletions api-playground/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,68 @@
---
title: 'Playground'
description: 'Enable users to interact with your API'
title: 'API Playground'
description: 'Try out API endpoints directly in your documentation'
openapi: 'GET /plants/{id}'
hideApiMarker: true
icon: 'play'
---

The API playground is an interactive environment to make requests and preview an API endpoint.
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!

<Info>
Autogenerating API pages with OpenAPI will automatically generate API
playground. Read more about using OpenAPI [here](/api-playground/openapi).
</Info>
## What Can You Do in the Playground?

<CardGroup cols={2}>
<Card title="Test Endpoints" icon="vial">
Make real API calls and see responses instantly
</Card>
<Card title="Fill Parameters" icon="sliders">
Input your own values for path, query, and body parameters
</Card>
<Card title="Authenticate" icon="key">
Add your API keys and authentication tokens
</Card>
<Card title="View Responses" icon="code">
See formatted API responses with syntax highlighting
</Card>
</CardGroup>

## Getting Started

The playground appears automatically on API documentation pages. Here's what you'll typically see:

1. **Authentication Fields** - Where you enter API keys or tokens
2. **Parameter Inputs** - Fields to enter your request data
3. **Try It Button** - Click to make the API call
4. **Response Section** - Shows the API response after your call

<Note>
If you're using OpenAPI to document your API, the playground will be generated automatically!
Learn more about OpenAPI setup [here](/api-playground/openapi).
</Note>

## Example Playground

Here's a simple example of what the playground looks like in action:

<Frame>
![API Playground Example](/images/api-playground-example.png)
</Frame>

## Tips for Using the Playground

<AccordionGroup>
<Accordion title="Save Time with Default Values" icon="clock">
The playground will pre-fill example values from your OpenAPI spec, making it faster to test endpoints.
</Accordion>

<Accordion title="Test Different Scenarios" icon="flask">
Try various parameter combinations to see how the API responds in different situations.
</Accordion>

<Accordion title="Check Error Responses" icon="bug">
Intentionally send invalid data to see how error responses look and understand error handling.
</Accordion>
</AccordionGroup>

<Tip>
Keep your API keys handy! You'll need them to make authenticated requests in the playground.
</Tip>
164 changes: 94 additions & 70 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,134 +1,158 @@
---
title: "Local Development"
description: "Preview changes locally to update your docs"
description: "Step-by-step guide to preview and test your documentation locally"
---

<Info>
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
</Info>
<Note>
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.
</Note>

**Step 1**: Install the Mintlify CLI:
## Setting Up Your Environment

<CodeGroup>
### Installing the CLI Tool

First, you'll need to install the Mintlify command-line interface (CLI). Choose one of these commands based on your package manager:

<CodeGroup>
```bash npm
npm i -g mintlify
```


```bash yarn
yarn global add mintlify
```


```bash pnpm
pnpm add -g mintlify
```

</CodeGroup>

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

```bash
mintlify dev
```
Once installed, follow these steps:

Alternatively, if you do not want to install the CLI globally you can use a run script available:
<Steps>
<Step title="Navigate to Your Docs">
Open your terminal and go to your documentation directory (where your `docs.json` file is located).
</Step>

<Step title="Start the Preview">
Run this command to start your local development server:
```bash
mintlify dev
```
</Step>

<CodeGroup>
<Step title="View Your Docs">
Open your browser and visit `http://localhost:3000` to see your documentation.
</Step>
</Steps>

```bash npm
npx mintlify dev
```
<Tip>
Don't want to install the CLI globally? You can use these run commands instead:

<CodeGroup>
```bash npm
npx mintlify dev

Check warning on line 56 in development.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

development.mdx#L56 

Did you really mean 'npx'?
```

```bash yarn
yarn dlx mintlify dev
```


```bash pnpm
pnpm dlx mintlify dev
```
```bash yarn
yarn dlx mintlify dev
```

</CodeGroup>

<Warning>
Yarn's "dlx" run script requires yarn version \>2. See [here](https://yarnpkg.com/cli/dlx) for more information.
</Warning>
```bash pnpm
pnpm dlx mintlify dev
```
</CodeGroup>
</Tip>

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

### Custom Ports
### Using a Different Port

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:
Need to run on a different port? Use the `--port` flag:

```bash
mintlify dev --port 3333
```

If you attempt to run on a port that's already in use, it will use the next available port:
<Info>
If the port you specify is already in use, Mintlify will automatically try the next available port.
</Info>

### Checking for Broken Links

Keep your documentation reliable by checking for broken links:

```md
Port 3000 is already in use. Trying 3001 instead.
```bash
mintlify broken-links
```

## Versions
### Updating Your CLI Version

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

<CodeGroup>

```bash npm
npm i -g mintlify@latest
```


```bash yarn
yarn global upgrade mintlify
```


```bash pnpm
pnpm up --global mintlify
```

</CodeGroup>

## Validating Links
## Best Practices

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

```bash
mintlify broken-links
```
<CardGroup cols={2}>
<Card title="MDX Extension" icon="brackets-curly">
Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting
</Card>
<Card title="Prettier" icon="wand-magic-sparkles">
Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to automatically format your documentation
</Card>
</CardGroup>

## Troubleshooting Guide

<AccordionGroup>
<Accordion title="Development server won't start" icon="circle-exclamation">
Try these steps in order:
1. Check your Node.js version (`node --version`)
2. Delete the `~/.mintlify` folder
3. Reinstall the CLI: `npm remove -g mintlify && npm install -g mintlify`
</Accordion>

<Accordion title='Error: "sharp" module not loading' icon="wrench">
This usually means you need to update Node.js:
1. Remove Mintlify: `npm remove -g mintlify`
2. Update to Node.js v19 or higher
3. Reinstall: `npm install -g mintlify`
</Accordion>

<Accordion title="Changes not showing up" icon="rotate">
Try these solutions:
1. Clear your browser cache
2. Restart the development server
3. Check for syntax errors in your MDX files
</Accordion>
</AccordionGroup>

## Deployment
## Deployment Status

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

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
alt="Successful deployment status showing green checkmarks"
/>
</Frame>

## Code Formatting

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.

## Troubleshooting

<AccordionGroup>
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
This may be due to an outdated version of node. Try the following:

1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
</Accordion>
<Accordion title="Issue: Encountering an unknown error">
Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run `mintlify dev` again.
</Accordion>
</AccordionGroup>
</Frame>
20 changes: 15 additions & 5 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,12 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor",
"quickstart",
"development"
]
},
"settings/global",
{
Expand All @@ -37,7 +42,9 @@
]
},
"themes",
"migration"
"migration",
"text",
"settings/global"
]
},
{
Expand Down Expand Up @@ -72,7 +79,8 @@
"api-playground/mdx/authentication"
]
},
"api-playground/troubleshooting"
"api-playground/troubleshooting",
"api-playground/overview"
]
},
{
Expand Down Expand Up @@ -262,7 +270,9 @@
"groups": [
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
]
}
Expand Down Expand Up @@ -374,4 +384,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
Loading
Loading