Improve content structure for better LLM indexing

api-playground/mdx/configuration.mdx

@@ -3,63 +3,161 @@ title: 'MDX Setup'
 description: 'Generate docs pages for your API endpoints using MDX'
 ---
 
-Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
+## Overview
 
-<Steps>
-  <Step title="Configure your API">
-    In your `mint.json` file, define your base URL and auth method:
+Mintlify allows you to define your API endpoints using three key components:
 
-    ```json
-    {
-      "api": {
-        "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
-        "auth": {
-          "method": "bearer" // options: bearer, basic, key.
-        }
-      }
+- Configuration in your `mint.json` file
+- MDX metadata fields for each endpoint
+- The `<ParamFields />` component for parameter documentation
+
+From these definitions, we automatically generate:
+
+- An interactive API playground
+- Request examples
+- Response examples
+
+## Base Configuration
+
+### API Base URL
+
+First, define your API's base URL in the `mint.json` file. You can specify a single URL or an array for multiple base URLs:
+
+```json
+{
+  "api": {
+    "baseUrl": "https://mintlify.com/api"
+  }
+}
+```
+
+For multiple base URLs:
+
+```json
+{
+  "api": {
+    "baseUrl": [
+      "https://api1.mintlify.com",
+      "https://api2.mintlify.com"
+    ]
+  }
+}
+```
+
+### Authentication Method
+
+Next, specify your API's authentication method in the same `api` section:
+
+```json
+{
+  "api": {
+    "auth": {
+      "method": "bearer" // options: bearer, basic, key
     }
-    ```
+  }
+}
+```
 
-    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:
+### Playground Settings
 
-    ```json
-    {
-      "api": {
-        "playground": {
-          "mode": "hide"
-        }
-      }
+By default, Mintlify shows an interactive API playground. You can hide this feature by adding:
+
+```json
+{
+  "api": {
+    "playground": {
+      "mode": "hide"
     }
-    ```
+  }
+}
+```
+
+<Info>
+  Find a complete list of API configurations in our [Global Settings](/settings/global#api-configurations) documentation.
+</Info>
+
+## Creating Endpoint Pages
+
+### Basic Structure
 
-    Find a full list of API configurations [here](/settings/global#api-configurations).
-  </Step>
-
-  <Step title="Create your endpoint pages">
+Each API endpoint needs its own MDX file. Start with this basic metadata structure:
 
-    Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
+```md
+---
+title: 'Create new user'
+api: 'POST https://api.mintlify.com/user'
+---
+```
+
+### Path Parameters
+
+For endpoints with path parameters, wrap the parameter name with curly braces `{}`:
+
+```bash
+https://api.example.com/v1/endpoint/{userId}
+```
 
-    ```md
-    ---
-    title: 'Create new user'
-    api: 'POST https://api.mintlify.com/user'
-    ---
-    ```
+### Using Base URL
+
+When you have configured `baseUrl` in your `mint.json`, you can use relative paths in your endpoint definitions:
+
+```md
+---
+title: 'Get User Profile'
+api: 'GET /v1/users/{userId}'
+---
+```
 
-    You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
+<Note>
+  The relative path will automatically be combined with your configured base URL.
+</Note>
 
-    ```bash
-    https://api.example.com/v1/endpoint/{userId}
-    ```
+## Navigation Setup
 
-    <Note>
+### Adding to Sidebar
 
-    If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
+Add your endpoint pages to the sidebar by including their paths in your `mint.json` navigation:
 
-    </Note>
-  </Step>
+```json
+{
+  "navigation": [
+    {
+      "group": "API Reference",
+      "pages": [
+        "api/create-user",
+        "api/get-user",
+        "api/update-user"
+      ]
+    }
+  ]
+}
+```
+
+### Organizing Endpoints
+
+For better organization, group related endpoints together in your navigation structure:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "User Management",
+      "pages": [
+        "api/users/create",
+        "api/users/get",
+        "api/users/update"
+      ]
+    },
+    {
+      "group": "Authentication",
+      "pages": [
+        "api/auth/login",
+        "api/auth/logout",
+        "api/auth/refresh"
+      ]
+    }
+  ]
+}
+```
 
-  <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 `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
-  </Step>
-</Steps>
+Learn more about structuring your docs in our [Navigation](/settings/navigation) guide.