mintlify · mintlify · Jan 16, 2025 · Feb 8, 2025
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
@@ -6,10 +6,57 @@
 icon: 'play'
 ---
 
-The API playground is an interactive environment to make requests and preview an API endpoint.
+## What is the API Playground?
+
+The API playground is an interactive environment that lets users test your API endpoints directly from your documentation. Think of it as a built-in API testing tool where users can:
+
+- Make real API requests
+- See exactly how the API behaves
+- Test different parameters and inputs
+- View formatted responses
+
+<Frame>
+  <img src="/images/api-playground-example.png" alt="Example of the API Playground interface" />
+</Frame>
+
+## Key Benefits
+
+<CardGroup cols={2}>
+  <Card title="Interactive Learning" icon="graduation-cap">
+    Users can learn your API hands-on instead of just reading about it
+  </Card>
+  <Card title="Quick Testing" icon="bolt">
+    Test endpoints instantly without setting up a separate API client
+  </Card>
+  <Card title="Real Responses" icon="server">
+    See actual API responses with your real data
+  </Card>
+  <Card title="Error Handling" icon="bug">
+    Understand how errors work by triggering them safely
+  </Card>
+</CardGroup>
+
+## Getting Started
+
+The easiest way to add API playground to your docs is by using OpenAPI (formerly known as Swagger). When you use OpenAPI:
+
+1. The playground is automatically generated for each endpoint
+2. All parameters and response formats are pre-configured
+3. Authentication is handled automatically
 
 <Info>
-  Autogenerating API pages with OpenAPI will automatically generate API
-  playground. Read more about using OpenAPI with Mintlify
-  [here](/api-playground/openapi).
+  Want to add API playground using OpenAPI? Check out our [OpenAPI setup guide](/api-playground/openapi) for step-by-step instructions.
 </Info>
+
+Don't have an OpenAPI specification? No problem! You can also set up the playground manually for each endpoint. We'll walk you through that in our [manual configuration guide](/api-playground/mdx).
+
+## Example
+
+Here's an example of what an API playground looks like when set up. Try making a request below:
+
+<Note>
+This is a live API playground example. Feel free to:
+- Change the parameters
+- Click "Send API Request"
+- See the actual response
+</Note>
diff --git a/development.mdx b/development.mdx
@@ -1,78 +1,93 @@
 ---
 title: 'Local Development'
-description: 'Preview changes locally to update your docs'
+description: 'Set up and preview your documentation locally'
 ---
 
 <Info>
 
-**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
-
+## Before You Start
+**Prerequisites**: 
+- Install Node.js version 19 or higher ([download here](https://nodejs.org/en))
+- Basic familiarity with command line/terminal
 </Info>
 
-**Step 1**: Install Mintlify:
-
-<CodeGroup>
+## Installation and Setup
 
-  ```bash npm
-  npm i -g mintlify
-  ```
+<Steps>
+  <Step title="Install the Mintlify CLI">
+    Choose any of the following package managers to install Mintlify globally on your machine:
 
-  ```bash yarn
-  yarn global add mintlify
-  ```
+    <CodeGroup>
 
-  ```bash pnpm
-  pnpm add -g mintlify
-  ```
+      ```bash npm
+      npm i -g mintlify
+      ```
 
-</CodeGroup>
+      ```bash yarn
+      yarn global add mintlify
+      ```
 
-**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
+      ```bash pnpm
+      pnpm add -g mintlify
+      ```
 
-```bash
-mintlify dev
-```
+    </CodeGroup>
+  </Step>
 
-Alternatively, if you do not want to install Mintlify globally you can use a run script available:
+  <Step title="Start the development server">
+    Navigate to your docs folder (where `docs.json` is located) and run:
 
-<CodeGroup>
-  ```bash npm
-  npx mintlify dev
-  ```
+    ```bash
+    mintlify dev
+    ```
 
-  ```bash yarn
-  yarn dlx mintlify dev
-  ```
+    The preview will be available at `http://localhost:3000`.
 
-  ```bash pnpm
-  pnpm dlx mintlify dev
-  ```
+    <Tip>
+      Don't want to install Mintlify globally? You can run it directly:
+      <CodeGroup>
+        ```bash npm
+        npx mintlify dev
+        ```
 
-</CodeGroup>
+        ```bash yarn
+        yarn dlx mintlify dev # Requires yarn >2
+        ```
 
-<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>
+  </Step>
+</Steps>
 
-A local preview of your documentation will be available at `http://localhost:3000`.
+## Common Configuration Options
 
-### Custom Ports
+### Change Preview Port
 
-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:
+By default, Mintlify runs on port 3000. You can use a different port by adding the `--port` flag:
 
 ```bash
 mintlify dev --port 3333
 ```
 
-If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
-
-```md
+If the specified port is in use, Mintlify will automatically try the next available port:
+```bash
 Port 3000 is already in use. Trying 3001 instead.
 ```
 
-## Mintlify Versions
+### Check for Broken Links
+
+Keep your documentation reliable by checking for broken links:
+
+```bash
+mintlify broken-links
+```
+
+## Updating Mintlify
 
-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:
+Each CLI release corresponds to a specific version of Mintlify. To ensure you have the latest features and fixes, update regularly:
 
 <CodeGroup>
 
@@ -90,42 +105,57 @@
 
 </CodeGroup>
 
-## Validating Links
+## Editor Setup
 
-The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
+For the best development experience, we recommend:
 
-```bash
-mintlify broken-links
-```
-
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-<Frame>
-  <img
-    className="rounded-md"
-    src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
-  />
-</Frame>
-
-## Code Formatting
+1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting
+2. Install [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for 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
+## Troubleshooting Guide
 
 <AccordionGroup>
-  <Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
+  <Accordion icon="triangle-exclamation" title='"sharp" module error with M1/M2 Macs'>
+    If you see `Error: Could not load the "sharp" module using the darwin-arm64 runtime`, follow these steps:
+
+    1. Remove current Mintlify installation:
+    ```bash
+    npm remove -g mintlify
+    ```
+
+    2. Upgrade Node.js to v19 or higher
+    3. Reinstall Mintlify:
+    ```bash
+    npm install -g mintlify
+    ```
+  </Accordion>
 
-    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 icon="folder" title="Unknown errors and cache issues">
+    If you encounter unexpected errors:
+    1. Delete the Mintlify cache folder:
+    ```bash
+    rm -rf ~/.mintlify
+    ```
+
+    2. Restart the development server:
+    ```bash
+    mintlify dev
+    ```
   </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 icon="check-double" title="Verify successful deployment">
+    When your deployment succeeds, you should see green checkmarks in your deployment status:
+
+    <Frame>
+      <img
+        className="rounded-md"
+        src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
+        alt="Successful deployment checks"
+      />
+    </Frame>
   </Accordion>
 </AccordionGroup>
+
+<Note>
+  Need more help? Join our [community](https://mintlify.com/community) or contact [[email protected]](mailto:[email protected])
+</Note>