Documentation edits made through Mintlify web editor

Author: mintlify[bot]

api-playground/mdx/configuration.mdx

@@ -1,74 +1,140 @@
 ---
 title: 'MDX Setup'
-description: 'Generate docs pages for your API endpoints using MDX'
+description: 'Learn how to create API documentation using MDX'
 ---
 
-Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
+Mintlify helps you create beautiful API documentation using MDX (Markdown + JSX). This guide will show you how to set up your API endpoints step by step.
+
+## Basic Setup
+
+Let's start with the simplest configuration possible:
 
 <Steps>
-  <Step title="Configure your API">
-    In your `docs.json` file, define your base URL and auth method:
+  <Step title="Create an API endpoint page">
+    Create a new MDX file for your API endpoint. At the top, add these basic details:
+
+    ```md
+    ---
+    title: 'List All Users'
+    api: 'GET /users'
+    ---
+    ```
+
+    That's all you need to get started! This will create a basic API documentation page.
+  </Step>
+
+  <Step title="Add it to your navigation">
+    Add your new page to the `navigation` section in your `docs.json` file:
 
     ```json
-     "api": {
-      "mdx": {
-        "server": "https://mintlify.com/api", // string array for multiple base URLs
-        "auth": {
-          "method": "key",
-          "name": "x-api-key" // options: bearer, basic, key.
+    {
+      "navigation": [
+        {
+          "group": "API Reference",
+          "pages": ["api-reference/list-users"]
         }
-      }
+      ]
     }
     ```
+  </Step>
+</Steps>
 
-    If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
+## Advanced Configuration
 
-    ```json
-    "api": {
-      "playground": {
-        "display": "none"
+Once you're comfortable with the basics, you can add more features to your API documentation.
+
+### Setting Up Your API Configuration
+
+In your `docs.json` file, you can define global settings for all your API endpoints:
+
+<CodeGroup>
+```json Basic Configuration
+{
+  "api": {
+    "mdx": {
+      "server": "https://api.example.com"
+    }
+  }
+}
+```
+
+```json Multiple Base URLs
+{
+  "api": {
+    "mdx": {
+      "server": [
+        "https://api.example.com",
+        "https://api-staging.example.com"
+      ]
+    }
+  }
+}
+```
+</CodeGroup>
+
+### Adding Authentication
+
+<Note>
+  Authentication settings let your users test API endpoints with their own API keys.
+</Note>
+
+Add authentication settings to your `docs.json`:
+
+```json
+{
+  "api": {
+    "mdx": {
+      "server": "https://api.example.com",
+      "auth": {
+        "method": "key",
+        "name": "x-api-key"
       }
     }
-    ```
-
-    Find a full list of API configurations [here](/core-concepts/settings#param-api).
-  </Step>
-  
-  <Step title="Create your endpoint pages">
+  }
+}
+```
 
-    Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
+### Path Parameters
 
-    ```md
-    ---
-    title: 'Create new user'
-    api: 'POST https://api.mintlify.com/user'
-    ---
-    ```
+You can include path parameters in your API endpoints using curly braces:
 
-    You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
+```md
+---
+title: 'Get User Details'
+api: 'GET /users/{userId}'
+---
+```
 
-    ```bash
-    https://api.example.com/v1/endpoint/{userId}
-    ```
+<Tip>
+  When you have `server` configured in docs.json, you can use shorter paths like `/users` instead of full URLs.
+</Tip>
 
-    <Note>
+### Customizing the API Playground
 
-    If you have `server` configured in [docs.json](/core-concepts/settings), you can use relative paths like `/v1/endpoint`.
+The API playground lets users test your endpoints directly in the documentation. You can control its display:
 
-    </Note>
+<CodeGroup>
+```json Hide Playground Everywhere
+{
+  "api": {
+    "playground": {
+      "display": "none"
+    }
+  }
+}
+```
 
-    You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file:
+```md Hide Playground on One Page
+---
+title: 'Create User'
+api: 'POST /users'
+playground: 'none'
+---
+```
+</CodeGroup>
 
-    ```md
-    ---
-    title: 'Create new user'
-    api: 'POST https://api.mintlify.com/user'
-    playground: 'none'
-    ```
-    
-  </Step>
+## Next Steps
 
-  <Step title="Add your endpoints to your docs">
-    Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](/core-concepts/navigation).
-  </Step>
-</Steps>
+- Learn more about [authentication options](/api-playground/mdx/authentication)
+- Explore [advanced API configurations](/core-concepts/settings#param-api)
+- See how to [structure your documentation](/core-concepts/navigation)