diff --git a/api/introduction.mdx b/api/introduction.mdx
index 5ebb15b73..091d606a0 100644
--- a/api/introduction.mdx
+++ b/api/introduction.mdx
@@ -26,6 +26,15 @@ The admin API key is used for the [Trigger update](/api-reference/update/trigger
 
 Admin API keys begin with the `mint_` prefix. Keep your admin API keys secret.
 
+**Example request:**
+
+```bash
+curl https://api.mintlify.com/v1/project/update/your-project-id \
+  -H "Authorization: Bearer mint_your_api_key" \
+  -H "Content-Type: application/json" \
+  -X POST
+```
+
 ### Assistant API key
 
 The assistant API key is used for the [Generate assistant message](/api-reference/assistant/create-assistant-message) and [Search documentation](/api-reference/assistant/search) endpoints.
@@ -36,6 +45,216 @@ The assistant API **key** is a server-side token that should be kept secret.
 
 The assistant API **token** is a public token that can be referenced in your frontend code.
 
+**Example request:**
+
+```bash
+curl https://api.mintlify.com/v1/assistant/message \
+  -H "Authorization: Bearer mint_dsc_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "domain": "docs.example.com",
+    "message": "How do I get started?"
+  }' \
+  -X POST
+```
+
 <Note>
   Calls using the assistant API token can incur costs: either using your AI assistant credits or incurring overages.
 </Note>
+
+## Rate limits
+
+API requests are rate limited to prevent abuse:
+
+| Endpoint Type | Rate Limit |
+|--------------|------------|
+| Admin endpoints | 100 requests per minute |
+| Assistant endpoints | 1000 requests per minute |
+
+When you exceed the rate limit, you'll receive a `429 Too Many Requests` response.
+
+## Error handling
+
+The API uses standard HTTP status codes to indicate success or failure:
+
+| Status Code | Description |
+|------------|-------------|
+| `200` | Success |
+| `400` | Bad request - check your request parameters |
+| `401` | Unauthorized - invalid or missing API key |
+| `403` | Forbidden - API key doesn't have access to this resource |
+| `404` | Not found - resource doesn't exist |
+| `429` | Too many requests - rate limit exceeded |
+| `500` | Internal server error - contact support |
+
+**Error response format:**
+
+```json
+{
+  "error": {
+    "code": "invalid_request",
+    "message": "The project ID is invalid",
+    "details": {
+      "field": "projectId",
+      "reason": "Project not found"
+    }
+  }
+}
+```
+
+**Handling errors in your code:**
+
+<CodeGroup>
+```javascript JavaScript
+try {
+  const response = await fetch('https://api.mintlify.com/v1/project/update/project-id', {
+    method: 'POST',
+    headers: {
+      'Authorization': 'Bearer mint_your_api_key',
+      'Content-Type': 'application/json'
+    }
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    console.error('API Error:', error.error.message);
+    
+    if (response.status === 429) {
+      // Handle rate limit - implement retry with backoff
+      console.log('Rate limited. Retrying after delay...');
+    }
+  }
+
+  const data = await response.json();
+  console.log('Success:', data);
+} catch (error) {
+  console.error('Network error:', error);
+}
+```
+
+```python Python
+import requests
+import time
+
+def call_api_with_retry(url, headers, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = requests.post(url, headers=headers)
+            
+            if response.status_code == 429:
+                # Rate limited - wait and retry
+                wait_time = 2 ** attempt  # Exponential backoff
+                print(f"Rate limited. Waiting {wait_time}s...")
+                time.sleep(wait_time)
+                continue
+            
+            response.raise_for_status()
+            return response.json()
+            
+        except requests.exceptions.HTTPError as e:
+            error_data = e.response.json()
+            print(f"API Error: {error_data['error']['message']}")
+            raise
+        except requests.exceptions.RequestException as e:
+            print(f"Network error: {e}")
+            raise
+    
+    raise Exception("Max retries exceeded")
+
+# Usage
+headers = {
+    'Authorization': 'Bearer mint_your_api_key',
+    'Content-Type': 'application/json'
+}
+result = call_api_with_retry(
+    'https://api.mintlify.com/v1/project/update/project-id',
+    headers
+)
+```
+
+```go Go
+package main
+
+import (
+    "bytes"
+    "encoding/json"
+    "fmt"
+    "io"
+    "net/http"
+    "time"
+)
+
+type APIError struct {
+    Error struct {
+        Code    string `json:"code"`
+        Message string `json:"message"`
+    } `json:"error"`
+}
+
+func callAPIWithRetry(url, apiKey string, maxRetries int) error {
+    client := &http.Client{Timeout: 10 * time.Second}
+    
+    for attempt := 0; attempt < maxRetries; attempt++ {
+        req, err := http.NewRequest("POST", url, nil)
+        if err != nil {
+            return err
+        }
+        
+        req.Header.Set("Authorization", "Bearer "+apiKey)
+        req.Header.Set("Content-Type", "application/json")
+        
+        resp, err := client.Do(req)
+        if err != nil {
+            return err
+        }
+        defer resp.Body.Close()
+        
+        if resp.StatusCode == 429 {
+            // Rate limited - exponential backoff
+            waitTime := time.Duration(1<<attempt) * time.Second
+            fmt.Printf("Rate limited. Waiting %v...\n", waitTime)
+            time.Sleep(waitTime)
+            continue
+        }
+        
+        if resp.StatusCode != 200 {
+            body, _ := io.ReadAll(resp.Body)
+            var apiErr APIError
+            json.Unmarshal(body, &apiErr)
+            return fmt.Errorf("API error: %s", apiErr.Error.Message)
+        }
+        
+        // Success
+        return nil
+    }
+    
+    return fmt.Errorf("max retries exceeded")
+}
+```
+</CodeGroup>
+
+## Best practices
+
+### Secure your API keys
+
+- Never commit API keys to version control
+- Use environment variables to store keys
+- Rotate keys regularly
+- Use separate keys for development and production
+
+### Implement retry logic
+
+Network requests can fail. Implement exponential backoff for retries:
+
+1. Wait 1 second after first failure
+2. Wait 2 seconds after second failure
+3. Wait 4 seconds after third failure
+4. Give up after 3-5 attempts
+
+### Monitor usage
+
+Track your API usage to:
+- Identify performance issues
+- Optimize request patterns
+- Stay within rate limits
+- Monitor costs (for assistant endpoints)
diff --git a/docs.json b/docs.json
index 89b194877..a05d7f07e 100644
--- a/docs.json
+++ b/docs.json
@@ -28,7 +28,8 @@
                   "index",
                   "quickstart",
                   "ai-native",
-                  "migration"
+                  "migration",
+                  "troubleshooting"
                 ]
               },
               {
@@ -63,56 +64,26 @@
                 ]
               },
               {
-                "group": "Create content",
+                "group": "Web editor",
                 "icon": "pen-line",
                 "pages": [
-                  {
-                    "group": "Web editor",
-                    "pages": [
-                      "editor/index",
-                      "editor/pages",
-                      "editor/media",
-                      "editor/navigation",
-                      "editor/configurations",
-                      "editor/collaborate",
-                      "editor/publish",
-                      "editor/keyboard-shortcuts"
-                    ]
-                  },
+                  "editor/index",
+                  "editor/pages",
+                  "editor/media",
+                  "editor/navigation",
+                  "editor/configurations",
+                  "editor/collaborate",
+                  "editor/publish",
+                  "editor/keyboard-shortcuts"
+                ]
+              },
+              {
+                "group": "Create content",
+                "icon": "file-text",
+                "pages": [
                   "installation",
                   "create/text",
                   "create/code",
-                  "ai/agent",
-                  "ai/suggestions",
-                  {
-                    "group": "Components",
-                    "pages": [
-                      "components/index",
-                      "components/accordions",
-                      "components/badge",
-                      "components/banner",
-                      "components/callouts",
-                      "components/cards",
-                      "components/code-groups",
-                      "components/color",
-                      "components/columns",
-                      "components/examples",
-                      "components/expandables",
-                      "components/fields",
-                      "components/frames",
-                      "components/icons",
-                      "components/mermaid-diagrams",
-                      "components/panel",
-                      "components/responses",
-                      "components/steps",
-                      "components/tabs",
-                      "components/tiles",
-                      "components/tooltips",
-                      "components/tree",
-                      "components/update",
-                      "components/view"
-                    ]
-                  },
                   "create/image-embeds",
                   "create/files",
                   "create/list-table",
@@ -121,6 +92,36 @@
                   "create/changelogs"
                 ]
               },
+              {
+                "group": "Components",
+                "icon": "blocks",
+                "pages": [
+                  "components/index",
+                  "components/accordions",
+                  "components/badge",
+                  "components/banner",
+                  "components/callouts",
+                  "components/cards",
+                  "components/code-groups",
+                  "components/color",
+                  "components/columns",
+                  "components/examples",
+                  "components/expandables",
+                  "components/fields",
+                  "components/frames",
+                  "components/icons",
+                  "components/mermaid-diagrams",
+                  "components/panel",
+                  "components/responses",
+                  "components/steps",
+                  "components/tabs",
+                  "components/tiles",
+                  "components/tooltips",
+                  "components/tree",
+                  "components/update",
+                  "components/view"
+                ]
+              },
               {
                 "group": "Document APIs",
                 "icon": "file-json",
@@ -137,11 +138,37 @@
                 ]
               },
               {
-                "group": "Deploy",
-                "icon": "boxes",
+                "group": "AI features",
+                "icon": "bot",
+                "pages": [
+                  "ai/agent",
+                  "ai/suggestions",
+                  "ai/assistant",
+                  "ai/discord",
+                  "ai/slack-bot",
+                  "ai/contextual-menu",
+                  "ai/llmstxt",
+                  "ai/model-context-protocol",
+                  "ai/markdown-export"
+                ]
+              },
+              {
+                "group": "Deployment",
+                "icon": "rocket",
                 "pages": [
                   "deploy/deployments",
                   "deploy/preview-deployments",
+                  "deploy/ci",
+                  "deploy/github",
+                  "deploy/ghes",
+                  "deploy/gitlab",
+                  "deploy/monorepo"
+                ]
+              },
+              {
+                "group": "Hosting",
+                "icon": "server",
+                "pages": [
                   {
                     "group": "/docs subpath",
                     "pages": [
@@ -155,22 +182,13 @@
                   },
                   "deploy/authentication-setup",
                   "deploy/personalization-setup",
-                  "deploy/monorepo",
-                  "deploy/vercel-external-proxies",
-                  "deploy/ci",
-                  "deploy/github",
-                  "deploy/ghes",
-                  "deploy/gitlab"
+                  "deploy/vercel-external-proxies"
                 ]
               },
               {
                 "group": "Optimize",
                 "icon": "wrench",
                 "pages": [
-                  "ai/assistant",
-                  "ai/discord",
-                  "ai/slack-bot",
-                  "ai/contextual-menu",
                   {
                     "group": "Insights",
                     "pages": [
@@ -178,10 +196,7 @@
                       "insights/feedback"
                     ]
                   },
-                  "ai/llmstxt",
-                  "ai/model-context-protocol",
                   "optimize/seo",
-                  "ai/markdown-export",
                   "optimize/pdf-exports",
                   {
                     "group": "Integrations",
@@ -258,9 +273,12 @@
                 ]
               },
               {
-                "group": "API docs",
-                "icon": "file-json",
+                "group": "Migration",
+                "icon": "arrow-right-arrow-left",
                 "pages": [
+                  "guides/migrate-from-gitbook",
+                  "guides/migrate-from-readme",
+                  "guides/migrate-from-docusaurus",
                   "guides/migrating-from-mdx"
                 ]
               },
@@ -275,10 +293,18 @@
                   "guides/media",
                   "guides/navigation",
                   "guides/seo",
+                  "guides/search-optimization",
                   "guides/style-and-tone",
                   "guides/understand-your-audience"
                 ]
               },
+              {
+                "group": "Comparisons",
+                "icon": "scale-balanced",
+                "pages": [
+                  "guides/deployment-comparison"
+                ]
+              },
               {
                 "group": "Git",
                 "icon": "git-merge",
diff --git a/guides/deployment-comparison.mdx b/guides/deployment-comparison.mdx
new file mode 100644
index 000000000..60c471399
--- /dev/null
+++ b/guides/deployment-comparison.mdx
@@ -0,0 +1,353 @@
+---
+title: Deployment options comparison
+description: Compare different deployment and hosting options for your Mintlify documentation
+---
+
+This guide compares deployment methods and hosting configurations to help you choose the right setup.
+
+## Deployment methods
+
+### GitHub integration (recommended)
+
+**Best for**: Most teams
+
+Automatic deployments triggered by Git pushes.
+
+**Pros:**
+- Automatic deployments on push
+- Preview deployments for pull requests
+- Full Git history and version control
+- Team collaboration through PRs
+- No manual deployment steps
+
+**Cons:**
+- Requires GitHub account
+- Deployment depends on GitHub availability
+
+**Setup:**
+1. Connect repository in dashboard
+2. Install GitHub App
+3. Push changes to deploy
+
+### GitLab integration
+
+**Best for**: Teams using GitLab
+
+Similar to GitHub with GitLab-specific features.
+
+**Pros:**
+- Automatic deployments on push
+- Works with self-hosted GitLab
+- GitLab CI/CD integration
+- Team collaboration
+
+**Cons:**
+- Requires GitLab account
+- Fewer integrations than GitHub
+
+**Setup:**
+1. Connect repository in dashboard
+2. Configure GitLab integration
+3. Push changes to deploy
+
+### CI/CD deployment
+
+**Best for**: Custom workflows, monorepos
+
+Deploy from any CI/CD system using the API.
+
+**Pros:**
+- Works with any Git provider
+- Custom deployment logic
+- Integration with existing CI/CD
+- Monorepo support
+
+**Cons:**
+- Requires API key management
+- Manual CI/CD configuration
+- No automatic preview deployments
+
+**Setup:**
+1. Generate API key in dashboard
+2. Configure CI/CD pipeline
+3. Call deployment API
+
+**Example (GitHub Actions):**
+```yaml
+name: Deploy Docs
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Trigger deployment
+        run: |
+          curl -X POST https://api.mintlify.com/v1/project/update/${{ secrets.PROJECT_ID }} \
+            -H "Authorization: Bearer ${{ secrets.MINTLIFY_API_KEY }}"
+```
+
+## Hosting configurations
+
+### Mintlify subdomain
+
+**Best for**: Quick setup, testing
+
+Your docs at `your-project.mintlify.app`.
+
+**Pros:**
+- Instant setup
+- Free SSL certificate
+- No DNS configuration
+- Automatic CDN
+
+**Cons:**
+- Mintlify branding in URL
+- Can't customize domain
+
+**Setup:**
+Automatic during onboarding.
+
+### Custom domain
+
+**Best for**: Production documentation
+
+Your docs at `docs.yourcompany.com`.
+
+**Pros:**
+- Professional appearance
+- Your branding
+- SEO benefits
+- Custom SSL certificate
+
+**Cons:**
+- Requires DNS configuration
+- 24-48 hour DNS propagation
+
+**Setup:**
+1. Add domain in dashboard
+2. Update DNS records (CNAME)
+3. Wait for SSL certificate
+
+### Subpath hosting
+
+**Best for**: Unified domain structure
+
+Your docs at `yourcompany.com/docs`.
+
+**Pros:**
+- Unified domain
+- Consistent branding
+- SEO consolidation
+- Existing domain authority
+
+**Cons:**
+- More complex setup
+- Requires reverse proxy or CDN
+- Additional configuration
+
+**Options:**
+- [Cloudflare](/deploy/cloudflare)
+- [AWS CloudFront](/deploy/route53-cloudfront)
+- [Vercel](/deploy/vercel)
+- [Reverse proxy](/deploy/reverse-proxy)
+
+## Comparison table
+
+| Feature | GitHub | GitLab | CI/CD | Mintlify Domain | Custom Domain | Subpath |
+|---------|--------|--------|-------|-----------------|---------------|---------|
+| **Setup time** | 5 min | 5 min | 15 min | Instant | 24-48 hrs | 1-2 hrs |
+| **Auto deploy** | ✓ | ✓ | ✓ | N/A | N/A | N/A |
+| **Preview deploys** | ✓ | ✓ | Custom | N/A | N/A | N/A |
+| **Custom domain** | N/A | N/A | N/A | ✗ | ✓ | ✓ |
+| **SSL certificate** | Auto | Auto | Auto | Auto | Auto | Manual |
+| **CDN** | ✓ | ✓ | ✓ | ✓ | ✓ | Depends |
+| **Cost** | Free | Free | Free | Free | Free | Varies |
+
+## Choosing the right setup
+
+### For startups and small teams
+
+**Recommended:**
+- GitHub integration
+- Mintlify subdomain initially
+- Custom domain when ready
+
+**Why:**
+- Fastest setup
+- Minimal configuration
+- Easy to upgrade later
+
+### For enterprises
+
+**Recommended:**
+- GitLab/GitHub integration
+- Custom domain
+- Subpath hosting (optional)
+
+**Why:**
+- Professional appearance
+- Brand consistency
+- Advanced security options
+
+### For monorepos
+
+**Recommended:**
+- CI/CD deployment
+- Custom domain
+- Monorepo configuration
+
+**Why:**
+- Flexible deployment
+- Works with existing setup
+- Multiple docs in one repo
+
+### For agencies
+
+**Recommended:**
+- GitHub integration
+- Custom domains for each client
+- Preview deployments
+
+**Why:**
+- Client branding
+- Easy client handoff
+- Professional workflow
+
+## Migration paths
+
+### From Mintlify subdomain to custom domain
+
+1. Add custom domain in dashboard
+2. Update DNS records
+3. Wait for SSL certificate
+4. Test custom domain
+5. Update links (optional)
+
+**Downtime:** None (both domains work during transition)
+
+### From custom domain to subpath
+
+1. Set up reverse proxy/CDN
+2. Configure subpath routing
+3. Update DNS records
+4. Test subpath access
+5. Set up redirects
+
+**Downtime:** Minimal (during DNS propagation)
+
+### From one Git provider to another
+
+1. Push code to new repository
+2. Connect new repository in dashboard
+3. Disconnect old repository
+4. Update team access
+
+**Downtime:** None (deployment continues)
+
+## Advanced configurations
+
+### Multiple environments
+
+Deploy different branches to different domains:
+
+| Branch | Domain | Purpose |
+|--------|--------|---------|
+| `main` | `docs.example.com` | Production |
+| `staging` | `staging-docs.example.com` | Staging |
+| `dev` | `dev-docs.example.com` | Development |
+
+### Geographic distribution
+
+Use CDN for global performance:
+
+- Automatic with Mintlify hosting
+- Configure with custom CDN for subpath
+- Edge caching for faster loads
+
+### Authentication
+
+Add authentication to protect docs:
+
+| Method | Best For | Setup |
+|--------|----------|-------|
+| Password | Simple protection | Dashboard config |
+| JWT | Custom auth | API integration |
+| OAuth | SSO integration | OAuth provider |
+
+## Performance considerations
+
+### Deployment speed
+
+| Method | Typical Deploy Time |
+|--------|-------------------|
+| GitHub | 2-3 minutes |
+| GitLab | 2-3 minutes |
+| CI/CD | 3-5 minutes |
+
+### Build optimization
+
+- Use preview deployments for testing
+- Deploy only changed files
+- Optimize images before committing
+- Minimize custom scripts
+
+## Security best practices
+
+### For all deployments
+
+- Use HTTPS (automatic with Mintlify)
+- Keep API keys secret
+- Rotate keys regularly
+- Use environment variables
+
+### For custom domains
+
+- Enable HSTS
+- Configure CSP headers
+- Use CAA DNS records
+- Monitor SSL certificate expiration
+
+### For CI/CD
+
+- Store API keys in secrets
+- Limit API key permissions
+- Use separate keys per environment
+- Audit deployment logs
+
+## Troubleshooting
+
+### Deployment not triggering
+
+**GitHub/GitLab:**
+- Check webhook configuration
+- Verify branch name matches
+- Review GitHub App permissions
+
+**CI/CD:**
+- Verify API key is valid
+- Check CI/CD logs
+- Ensure correct project ID
+
+### Custom domain not working
+
+- Verify DNS records
+- Wait 24-48 hours for propagation
+- Check SSL certificate status
+- Clear browser cache
+
+### Slow deployments
+
+- Optimize image sizes
+- Reduce number of pages
+- Check for large files
+- Review custom scripts
+
+## Getting help
+
+For deployment issues:
+- Check [troubleshooting guide](/troubleshooting)
+- Review [deployment documentation](/deploy/deployments)
+- [Contact support](https://www.mintlify.com/docs/contact-support)
diff --git a/guides/migrate-from-docusaurus.mdx b/guides/migrate-from-docusaurus.mdx
new file mode 100644
index 000000000..af9b054f9
--- /dev/null
+++ b/guides/migrate-from-docusaurus.mdx
@@ -0,0 +1,520 @@
+---
+title: Migrate from Docusaurus
+description: Step-by-step guide to migrate your documentation from Docusaurus to Mintlify
+---
+
+This guide walks you through migrating your documentation from Docusaurus to Mintlify.
+
+## Before you start
+
+<Steps>
+  <Step title="Use the automated scraper">
+    Mintlify provides an automated scraper for Docusaurus:
+    
+    ```bash
+    npm install @mintlify/scraping@latest -g
+    mintlify-scrape section https://your-docs-site.com
+    ```
+  </Step>
+  
+  <Step title="Or migrate manually">
+    For more control, manually convert your Docusaurus project. Your content is already in Markdown/MDX format, making migration straightforward.
+  </Step>
+</Steps>
+
+## Migration process
+
+### 1. Understand Docusaurus structure
+
+Typical Docusaurus project:
+
+```
+docs/
+├── intro.md
+├── getting-started/
+│   ├── installation.md
+│   └── configuration.md
+└── api/
+    └── reference.md
+docusaurus.config.js
+sidebars.js
+```
+
+### 2. Convert navigation
+
+**Docusaurus `sidebars.js`:**
+```javascript
+module.exports = {
+  docs: [
+    'intro',
+    {
+      type: 'category',
+      label: 'Getting Started',
+      items: ['getting-started/installation', 'getting-started/configuration'],
+    },
+    {
+      type: 'category',
+      label: 'API',
+      items: ['api/reference'],
+    },
+  ],
+};
+```
+
+**Mintlify `docs.json`:**
+```json
+{
+  "navigation": {
+    "pages": [
+      "intro",
+      {
+        "group": "Getting started",
+        "pages": [
+          "getting-started/installation",
+          "getting-started/configuration"
+        ]
+      },
+      {
+        "group": "API",
+        "pages": ["api/reference"]
+      }
+    ]
+  }
+}
+```
+
+### 3. Update frontmatter
+
+Docusaurus and Mintlify use similar frontmatter, but with some differences:
+
+**Docusaurus:**
+```markdown
+---
+id: my-doc
+title: My Document
+sidebar_label: My Doc
+sidebar_position: 1
+---
+```
+
+**Mintlify:**
+```mdx
+---
+title: My Document
+sidebarTitle: My Doc
+description: Brief description of the page
+---
+```
+
+Key changes:
+- Remove `id` (use filename instead)
+- Remove `sidebar_position` (use navigation order in `docs.json`)
+- Add `description` for SEO
+- Rename `sidebar_label` to `sidebarTitle`
+
+### 4. Convert Docusaurus-specific syntax
+
+#### Admonitions
+
+**Docusaurus:**
+```markdown
+:::note
+This is a note
+:::
+
+:::tip
+This is a tip
+:::
+
+:::warning
+This is a warning
+:::
+
+:::danger
+This is dangerous
+:::
+
+:::info
+This is info
+:::
+```
+
+**Mintlify:**
+```mdx
+<Note>
+This is a note
+</Note>
+
+<Tip>
+This is a tip
+</Tip>
+
+<Warning>
+This is a warning
+</Warning>
+
+<Danger>
+This is dangerous
+</Danger>
+
+<Info>
+This is info
+</Info>
+```
+
+#### Tabs
+
+**Docusaurus:**
+```markdown
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="js" label="JavaScript">
+    ```js
+    console.log('Hello');
+    ```
+  </TabItem>
+  <TabItem value="py" label="Python">
+    ```py
+    print('Hello')
+    ```
+  </TabItem>
+</Tabs>
+```
+
+**Mintlify:**
+```mdx
+<Tabs>
+  <Tab title="JavaScript">
+    ```javascript
+    console.log('Hello');
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    print('Hello')
+    ```
+  </Tab>
+</Tabs>
+```
+
+Or use CodeGroup for code-only tabs:
+
+```mdx
+<CodeGroup>
+```javascript JavaScript
+console.log('Hello');
+```
+
+```python Python
+print('Hello')
+```
+</CodeGroup>
+```
+
+#### Code blocks with titles
+
+**Docusaurus:**
+```markdown
+```jsx title="src/App.js"
+function App() {
+  return <div>Hello</div>;
+}
+```
+```
+
+**Mintlify:**
+```mdx
+```jsx src/App.js
+function App() {
+  return <div>Hello</div>;
+}
+```
+```
+
+#### Details/Summary
+
+**Docusaurus:**
+```markdown
+<details>
+  <summary>Click to expand</summary>
+  Hidden content here
+</details>
+```
+
+**Mintlify:**
+```mdx
+<Accordion title="Click to expand">
+  Hidden content here
+</Accordion>
+```
+
+#### MDX imports
+
+**Docusaurus:**
+```mdx
+import MyComponent from '@site/src/components/MyComponent';
+
+<MyComponent />
+```
+
+**Mintlify:**
+
+Create React components in your project and import them:
+
+```mdx
+import MyComponent from '/snippets/MyComponent.mdx';
+
+<MyComponent />
+```
+
+### 5. Migrate assets
+
+Move static assets:
+
+```bash
+# Copy from Docusaurus static folder
+cp -r static/img images/
+```
+
+Update image references:
+
+**Before:**
+```markdown
+![Alt text](/img/screenshot.png)
+```
+
+**After:**
+```mdx
+![Alt text](/images/screenshot.png)
+```
+
+### 6. Convert configuration
+
+**Docusaurus `docusaurus.config.js`:**
+```javascript
+module.exports = {
+  title: 'My Site',
+  tagline: 'My awesome site',
+  url: 'https://mysite.com',
+  baseUrl: '/',
+  favicon: 'img/favicon.ico',
+  themeConfig: {
+    navbar: {
+      logo: {
+        src: 'img/logo.svg',
+      },
+    },
+    colorMode: {
+      defaultMode: 'light',
+    },
+  },
+};
+```
+
+**Mintlify `docs.json`:**
+```json
+{
+  "name": "My Site",
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "favicon": "/favicon.ico",
+  "colors": {
+    "primary": "#0D9373",
+    "light": "#07C983",
+    "dark": "#0D9373"
+  }
+}
+```
+
+### 7. Handle Docusaurus plugins
+
+#### Search
+
+Docusaurus uses Algolia DocSearch. Mintlify has built-in search:
+
+- Remove Algolia configuration
+- Search works automatically after deployment
+- No additional setup needed
+
+#### Analytics
+
+**Docusaurus:**
+```javascript
+gtag: {
+  trackingID: 'G-XXXXXXXXXX',
+}
+```
+
+**Mintlify:**
+```json
+{
+  "integrations": {
+    "ga4": {
+      "measurementId": "G-XXXXXXXXXX"
+    }
+  }
+}
+```
+
+#### Versioning
+
+**Docusaurus versions:**
+```
+versions.json
+versioned_docs/
+versioned_sidebars/
+```
+
+**Mintlify versions:**
+```json
+{
+  "versions": [
+    {
+      "version": "2.0",
+      "navigation": {
+        "pages": ["v2/introduction"]
+      }
+    },
+    {
+      "version": "1.0",
+      "navigation": {
+        "pages": ["v1/introduction"]
+      }
+    }
+  ]
+}
+```
+
+### 8. Convert custom React components
+
+Docusaurus allows custom React components. In Mintlify:
+
+1. Create MDX snippet files
+2. Use Mintlify's built-in components when possible
+3. For custom components, use React components in MDX
+
+**Example:**
+
+Create `snippets/CustomCard.mdx`:
+```mdx
+<Card title="Custom Card" icon="star">
+  Custom content here
+</Card>
+```
+
+Use in pages:
+```mdx
+import CustomCard from '/snippets/CustomCard.mdx';
+
+<CustomCard />
+```
+
+### 9. Update internal links
+
+**Docusaurus:**
+```markdown
+[Link](./other-page.md)
+[Link with anchor](../category/page.md#section)
+```
+
+**Mintlify:**
+```mdx
+[Link](/other-page)
+[Link with anchor](/category/page#section)
+```
+
+Remove `.md` extensions and use absolute paths.
+
+## Testing your migration
+
+Run locally:
+
+```bash
+mintlify dev
+```
+
+Verify:
+- All pages render
+- Navigation works
+- Components display correctly
+- Images load
+- Links resolve
+- Code blocks have syntax highlighting
+
+## Common migration issues
+
+### Broken imports
+
+**Problem**: Docusaurus `@site` imports don't work.
+
+**Solution**: Use relative paths or Mintlify's snippet system.
+
+### Missing plugins
+
+**Problem**: Docusaurus plugins not available.
+
+**Solution**: 
+- Use Mintlify's built-in features
+- Add custom scripts via `docs.json`
+- Use integrations for analytics, etc.
+
+### Swizzled components
+
+**Problem**: Customized Docusaurus theme components.
+
+**Solution**: 
+- Use Mintlify's theming options
+- Add custom CSS
+- Use React components for custom UI
+
+### Base URL issues
+
+**Problem**: Site was hosted at `/docs` subpath.
+
+**Solution**: Configure subpath in Mintlify or use redirects.
+
+## Deployment
+
+After migration:
+
+1. Push to GitHub
+2. Connect repository in Mintlify dashboard
+3. Configure custom domain
+4. Set up redirects from old URLs:
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/docs/:slug*",
+      "destination": "/:slug*"
+    }
+  ]
+}
+```
+
+## Feature comparison
+
+| Docusaurus Feature | Mintlify Equivalent |
+|-------------------|---------------------|
+| Sidebars | Navigation in docs.json |
+| Admonitions | Callout components |
+| Tabs | Tabs/CodeGroup |
+| Versioning | Versions in docs.json |
+| i18n | Languages in docs.json |
+| Algolia Search | Built-in search |
+| Blog | Changelog |
+| Custom CSS | Custom scripts |
+| Plugins | Integrations |
+
+## Getting help
+
+Need assistance?
+
+- Check the [troubleshooting guide](/troubleshooting)
+- Review [Mintlify components](/components/index)
+- [Contact support](https://www.mintlify.com/docs/contact-support)
diff --git a/guides/migrate-from-gitbook.mdx b/guides/migrate-from-gitbook.mdx
new file mode 100644
index 000000000..21f034b97
--- /dev/null
+++ b/guides/migrate-from-gitbook.mdx
@@ -0,0 +1,341 @@
+---
+title: Migrate from GitBook
+description: Step-by-step guide to migrate your documentation from GitBook to Mintlify
+---
+
+This guide walks you through migrating your documentation from GitBook to Mintlify.
+
+## Before you start
+
+<Steps>
+  <Step title="Export your GitBook content">
+    GitBook stores content in Markdown format. Export your content:
+    
+    1. Go to your GitBook space settings
+    2. Navigate to **Advanced** → **Export**
+    3. Choose **Markdown & Images** format
+    4. Download the ZIP file
+  </Step>
+  
+  <Step title="Set up your Mintlify project">
+    If you haven't already, create a new Mintlify project:
+    
+    ```bash
+    npm i -g mintlify
+    mintlify init
+    ```
+  </Step>
+</Steps>
+
+## Migration process
+
+### 1. Extract and organize content
+
+Extract your GitBook export and review the structure:
+
+```
+gitbook-export/
+├── README.md
+├── SUMMARY.md
+├── page-1.md
+├── page-2.md
+└── .gitbook/
+    └── assets/
+```
+
+GitBook uses `SUMMARY.md` for navigation. You'll convert this to Mintlify's `docs.json` format.
+
+### 2. Convert navigation structure
+
+GitBook's `SUMMARY.md` looks like this:
+
+```markdown
+# Table of contents
+
+* [Introduction](README.md)
+* [Getting Started](getting-started.md)
+  * [Installation](getting-started/installation.md)
+  * [Configuration](getting-started/configuration.md)
+* [API Reference](api-reference/README.md)
+  * [Authentication](api-reference/authentication.md)
+```
+
+Convert this to Mintlify's `docs.json` navigation:
+
+```json
+{
+  "navigation": {
+    "pages": [
+      "introduction",
+      {
+        "group": "Getting started",
+        "pages": [
+          "getting-started/installation",
+          "getting-started/configuration"
+        ]
+      },
+      {
+        "group": "API reference",
+        "pages": [
+          "api-reference/overview",
+          "api-reference/authentication"
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 3. Update frontmatter
+
+GitBook files may have minimal or no frontmatter. Add Mintlify frontmatter to each file:
+
+**Before (GitBook):**
+```markdown
+# Page Title
+
+Content here...
+```
+
+**After (Mintlify):**
+```mdx
+---
+title: Page Title
+description: Brief description of this page
+---
+
+Content here...
+```
+
+### 4. Convert GitBook-specific syntax
+
+#### Hints and callouts
+
+**GitBook syntax:**
+```markdown
+{% hint style="info" %}
+This is an info hint
+{% endhint %}
+
+{% hint style="warning" %}
+This is a warning
+{% endhint %}
+```
+
+**Mintlify syntax:**
+```mdx
+<Info>
+This is an info hint
+</Info>
+
+<Warning>
+This is a warning
+</Warning>
+```
+
+#### Tabs
+
+**GitBook syntax:**
+```markdown
+{% tabs %}
+{% tab title="JavaScript" %}
+```javascript
+console.log('Hello');
+```
+{% endtab %}
+
+{% tab title="Python" %}
+```python
+print('Hello')
+```
+{% endtab %}
+{% endtabs %}
+```
+
+**Mintlify syntax:**
+```mdx
+<CodeGroup>
+```javascript JavaScript
+console.log('Hello');
+```
+
+```python Python
+print('Hello')
+```
+</CodeGroup>
+```
+
+#### Page links
+
+**GitBook syntax:**
+```markdown
+[Link text](../other-page.md)
+[Link with anchor](page.md#section)
+```
+
+**Mintlify syntax:**
+```mdx
+[Link text](/other-page)
+[Link with anchor](/page#section)
+```
+
+Remove `.md` extensions and use absolute paths from the root.
+
+#### Embedded content
+
+**GitBook syntax:**
+```markdown
+{% embed url="https://www.youtube.com/watch?v=VIDEO_ID" %}
+```
+
+**Mintlify syntax:**
+```mdx
+<Frame>
+  <iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/VIDEO_ID"
+    frameBorder="0"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+    allowFullScreen
+  />
+</Frame>
+```
+
+### 5. Migrate assets
+
+Move images from `.gitbook/assets/` to your Mintlify project:
+
+```bash
+mkdir -p images
+cp -r .gitbook/assets/* images/
+```
+
+Update image references in your Markdown files:
+
+**Before:**
+```markdown
+![Alt text](.gitbook/assets/image.png)
+```
+
+**After:**
+```mdx
+![Alt text](/images/image.png)
+```
+
+### 6. Handle special GitBook features
+
+#### API documentation
+
+If you used GitBook's API blocks, convert them to OpenAPI format:
+
+1. Create an OpenAPI specification file
+2. Add it to your `docs.json`:
+
+```json
+{
+  "openapi": "/path/to/openapi.json",
+  "navigation": {
+    "pages": [
+      {
+        "group": "API reference",
+        "openapi": "/path/to/openapi.json",
+        "pages": ["GET /users", "POST /users"]
+      }
+    ]
+  }
+}
+```
+
+#### Integrations
+
+GitBook integrations need to be reconfigured in Mintlify:
+
+- **Analytics**: Add to `docs.json` under `integrations`
+- **Search**: Built-in with Mintlify
+- **Custom scripts**: Add to `docs.json` under `scripts`
+
+### 7. Configure settings
+
+Update your `docs.json` with GitBook-equivalent settings:
+
+```json
+{
+  "name": "Your Docs",
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "colors": {
+    "primary": "#0D9373",
+    "light": "#07C983",
+    "dark": "#0D9373"
+  },
+  "favicon": "/favicon.png",
+  "navigation": {
+    // Your navigation structure
+  }
+}
+```
+
+## Testing your migration
+
+Before deploying, test locally:
+
+```bash
+mintlify dev
+```
+
+Check for:
+- All pages render correctly
+- Navigation works as expected
+- Images load properly
+- Links resolve correctly
+- Code blocks display with syntax highlighting
+- Components render properly
+
+## Common migration issues
+
+### Broken internal links
+
+**Problem**: Links don't work after migration.
+
+**Solution**: 
+- Remove `.md` extensions from links
+- Use absolute paths from root (e.g., `/getting-started/installation`)
+- Update anchor links to use lowercase with hyphens
+
+### Missing images
+
+**Problem**: Images don't display.
+
+**Solution**:
+- Verify images are in the `images/` directory
+- Update paths to use `/images/` prefix
+- Check file names match exactly (case-sensitive)
+
+### Unsupported GitBook syntax
+
+**Problem**: GitBook-specific syntax doesn't render.
+
+**Solution**:
+- Replace `{% hint %}` blocks with Mintlify callouts
+- Convert `{% tabs %}` to `<CodeGroup>` or `<Tabs>`
+- Replace `{% embed %}` with `<Frame>` components
+
+## Deployment
+
+Once your migration is complete:
+
+1. Push your code to GitHub
+2. Connect your repository in the Mintlify dashboard
+3. Configure your custom domain (if applicable)
+4. Set up redirects from your old GitBook URLs
+
+## Getting help
+
+If you encounter issues during migration:
+
+- Check the [troubleshooting guide](/troubleshooting)
+- Review [Mintlify components](/components/index)
+- [Contact support](https://www.mintlify.com/docs/contact-support)
diff --git a/guides/migrate-from-readme.mdx b/guides/migrate-from-readme.mdx
new file mode 100644
index 000000000..5434022b1
--- /dev/null
+++ b/guides/migrate-from-readme.mdx
@@ -0,0 +1,461 @@
+---
+title: Migrate from ReadMe
+description: Step-by-step guide to migrate your documentation from ReadMe to Mintlify
+---
+
+This guide walks you through migrating your documentation from ReadMe to Mintlify.
+
+## Before you start
+
+<Steps>
+  <Step title="Use the automated scraper">
+    Mintlify provides an automated scraper for ReadMe. This is the recommended approach:
+    
+    ```bash
+    npm install @mintlify/scraping@latest -g
+    mintlify-scrape section https://your-docs.readme.io
+    ```
+    
+    For large sites, migrate sections individually.
+  </Step>
+  
+  <Step title="Or export manually">
+    If you prefer manual control:
+    
+    1. Access your ReadMe dashboard
+    2. Navigate to each page and copy the Markdown content
+    3. Save locally for conversion
+  </Step>
+</Steps>
+
+## Migration process
+
+### 1. Understand ReadMe structure
+
+ReadMe organizes content into:
+- **Categories**: Top-level groups
+- **Pages**: Individual documentation pages
+- **API Reference**: Auto-generated from OpenAPI specs
+
+Mintlify uses a similar structure with groups and pages in `docs.json`.
+
+### 2. Convert navigation
+
+**ReadMe structure:**
+```
+Getting Started
+├── Introduction
+├── Quickstart
+└── Installation
+
+API Reference
+├── Authentication
+├── Users
+└── Webhooks
+```
+
+**Mintlify `docs.json`:**
+```json
+{
+  "navigation": {
+    "pages": [
+      {
+        "group": "Getting started",
+        "pages": [
+          "introduction",
+          "quickstart",
+          "installation"
+        ]
+      },
+      {
+        "group": "API reference",
+        "pages": [
+          "api-reference/authentication",
+          "api-reference/users",
+          "api-reference/webhooks"
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 3. Convert ReadMe-specific syntax
+
+#### Callouts
+
+**ReadMe syntax:**
+```markdown
+[block:callout]
+{
+  "type": "info",
+  "title": "Note",
+  "body": "This is important information"
+}
+[/block]
+```
+
+**Mintlify syntax:**
+```mdx
+<Info>
+**Note**
+
+This is important information
+</Info>
+```
+
+Available callout types:
+- `info` → `<Info>`
+- `warning` → `<Warning>`
+- `danger` → `<Danger>`
+- `success` → `<Check>`
+
+#### Code blocks
+
+**ReadMe syntax:**
+```markdown
+[block:code]
+{
+  "codes": [
+    {
+      "code": "console.log('Hello');",
+      "language": "javascript",
+      "name": "JavaScript"
+    },
+    {
+      "code": "print('Hello')",
+      "language": "python",
+      "name": "Python"
+    }
+  ]
+}
+[/block]
+```
+
+**Mintlify syntax:**
+```mdx
+<CodeGroup>
+```javascript JavaScript
+console.log('Hello');
+```
+
+```python Python
+print('Hello')
+```
+</CodeGroup>
+```
+
+#### API blocks
+
+**ReadMe syntax:**
+```markdown
+[block:api-header]
+{
+  "title": "Get User"
+}
+[/block]
+
+[block:parameters]
+{
+  "data": {
+    "h-0": "Parameter",
+    "h-1": "Type",
+    "h-2": "Description",
+    "0-0": "id",
+    "0-1": "string",
+    "0-2": "User ID"
+  }
+}
+[/block]
+```
+
+**Mintlify approach:**
+
+Use OpenAPI specifications instead. Create an `openapi.json` file:
+
+```json
+{
+  "openapi": "3.0.0",
+  "paths": {
+    "/users/{id}": {
+      "get": {
+        "summary": "Get User",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "User ID"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Then reference in `docs.json`:
+
+```json
+{
+  "openapi": "/openapi.json",
+  "navigation": {
+    "pages": [
+      {
+        "group": "API reference",
+        "openapi": "/openapi.json",
+        "pages": ["GET /users/{id}"]
+      }
+    ]
+  }
+}
+```
+
+#### Embedded content
+
+**ReadMe syntax:**
+```markdown
+[block:embed]
+{
+  "html": "<iframe src='...'></iframe>",
+  "url": "https://example.com",
+  "title": "Example"
+}
+[/block]
+```
+
+**Mintlify syntax:**
+```mdx
+<Frame>
+  <iframe src="https://example.com" />
+</Frame>
+```
+
+#### Images
+
+**ReadMe syntax:**
+```markdown
+[block:image]
+{
+  "images": [
+    {
+      "image": [
+        "https://files.readme.io/abc123.png",
+        "image.png",
+        100,
+        200,
+        "#fff"
+      ],
+      "caption": "Image caption"
+    }
+  ]
+}
+[/block]
+```
+
+**Mintlify syntax:**
+```mdx
+<Frame caption="Image caption">
+  <img src="/images/image.png" alt="Image caption" />
+</Frame>
+```
+
+### 4. Migrate API documentation
+
+If you have OpenAPI specs in ReadMe:
+
+1. Export your OpenAPI specification from ReadMe
+2. Add it to your Mintlify project
+3. Configure in `docs.json`:
+
+```json
+{
+  "openapi": "/openapi.json",
+  "api": {
+    "baseUrl": "https://api.example.com",
+    "auth": {
+      "method": "bearer"
+    }
+  }
+}
+```
+
+### 5. Handle ReadMe features
+
+#### Variables
+
+**ReadMe:**
+```markdown
+<<glossary:API_KEY>>
+```
+
+**Mintlify:**
+
+Use MDX variables or environment-specific content:
+
+```mdx
+<ParamField path="api_key" type="string">
+  Your API key from the dashboard
+</ParamField>
+```
+
+#### Suggested edits
+
+ReadMe's suggested edits feature doesn't have a direct equivalent. Use Git-based workflows:
+
+1. Enable GitHub/GitLab integration
+2. Contributors create pull requests
+3. Review and merge changes
+
+#### Versioning
+
+**ReadMe versions** → **Mintlify versions**
+
+Configure in `docs.json`:
+
+```json
+{
+  "versions": [
+    {
+      "version": "v2.0",
+      "navigation": {
+        "pages": ["v2/introduction"]
+      }
+    },
+    {
+      "version": "v1.0",
+      "navigation": {
+        "pages": ["v1/introduction"]
+      }
+    }
+  ]
+}
+```
+
+### 6. Migrate custom CSS and scripts
+
+**ReadMe custom CSS:**
+
+Add to your Mintlify project:
+
+```json
+{
+  "customScripts": [
+    "/custom.css"
+  ]
+}
+```
+
+Create `public/custom.css` with your styles.
+
+### 7. Set up analytics
+
+ReadMe analytics → Mintlify integrations
+
+```json
+{
+  "integrations": {
+    "ga4": {
+      "measurementId": "G-XXXXXXXXXX"
+    },
+    "mixpanel": {
+      "projectToken": "your-token"
+    }
+  }
+}
+```
+
+## Testing your migration
+
+Run locally to verify:
+
+```bash
+mintlify dev
+```
+
+Check:
+- All pages render correctly
+- API playground works
+- Code examples display properly
+- Images load
+- Links work
+- Search functions correctly
+
+## Common migration issues
+
+### Block syntax not converting
+
+**Problem**: ReadMe `[block:...]` syntax appears as plain text.
+
+**Solution**: Use the automated scraper or manually convert to Mintlify components.
+
+### API reference not displaying
+
+**Problem**: API endpoints don't show up.
+
+**Solution**:
+- Verify OpenAPI spec is valid
+- Check `openapi` path in `docs.json`
+- Ensure page names match OpenAPI operation IDs
+
+### Missing custom domain
+
+**Problem**: Need to maintain existing domain.
+
+**Solution**:
+1. Configure custom domain in Mintlify dashboard
+2. Update DNS records
+3. Set up redirects from old URLs
+
+### Lost search functionality
+
+**Problem**: Search doesn't work as expected.
+
+**Solution**:
+- Ensure all pages are in navigation
+- Add descriptive titles and descriptions
+- Wait for search index to rebuild (5-10 minutes after deployment)
+
+## Deployment
+
+After migration:
+
+1. Push to GitHub/GitLab
+2. Connect repository in Mintlify dashboard
+3. Configure custom domain
+4. Set up redirects:
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/docs/:slug*",
+      "destination": "/:slug*"
+    }
+  ]
+}
+```
+
+## Feature comparison
+
+| ReadMe Feature | Mintlify Equivalent |
+|----------------|---------------------|
+| Categories | Groups in navigation |
+| Suggested Edits | Git pull requests |
+| API Explorer | API Playground |
+| Custom CSS | Custom scripts |
+| Metrics | Analytics integrations |
+| Versioning | Versions in docs.json |
+| Variables | MDX variables |
+| Changelog | Changelog pages |
+
+## Getting help
+
+Need assistance with migration?
+
+- Review the [troubleshooting guide](/troubleshooting)
+- Check [API playground setup](/api-playground/overview)
+- [Contact support](https://www.mintlify.com/docs/contact-support)
diff --git a/guides/search-optimization.mdx b/guides/search-optimization.mdx
new file mode 100644
index 000000000..c32c3a580
--- /dev/null
+++ b/guides/search-optimization.mdx
@@ -0,0 +1,360 @@
+---
+title: Search optimization
+description: Improve discoverability of your documentation through better search results
+---
+
+Mintlify provides built-in search functionality. This guide helps you optimize your content for better search results.
+
+## How search works
+
+Mintlify's search indexes:
+- Page titles and descriptions
+- Headings (H1, H2, H3)
+- Body content
+- Code block titles
+- Component content
+
+Search results are ranked by:
+1. **Relevance**: How well the query matches the content
+2. **Title matches**: Exact matches in titles rank higher
+3. **Heading matches**: Matches in headings rank higher than body text
+4. **Recency**: Recently updated pages may rank higher
+
+## Optimize page metadata
+
+### Write descriptive titles
+
+**Good titles:**
+- "Install the CLI"
+- "Configure authentication"
+- "Troubleshoot build errors"
+
+**Poor titles:**
+- "Getting Started" (too generic)
+- "Page 1" (not descriptive)
+- "CLI" (too short)
+
+### Add meaningful descriptions
+
+Descriptions appear in search results and help users decide if a page is relevant.
+
+**Good description:**
+```yaml
+---
+title: Install the CLI
+description: Install the Mintlify CLI to preview and develop your documentation locally
+---
+```
+
+**Poor description:**
+```yaml
+---
+title: Install the CLI
+description: Learn about the CLI
+---
+```
+
+### Use relevant keywords
+
+Add keywords to frontmatter for better discoverability:
+
+```yaml
+---
+title: Install the CLI
+description: Install the Mintlify CLI to preview and develop your documentation locally
+keywords: ["CLI", "installation", "local development", "preview", "npm"]
+---
+```
+
+## Structure content for search
+
+### Use clear headings
+
+Break content into sections with descriptive headings:
+
+```mdx
+## Install on macOS
+
+Instructions for macOS...
+
+## Install on Windows
+
+Instructions for Windows...
+
+## Install on Linux
+
+Instructions for Linux...
+```
+
+This helps users find specific sections through search.
+
+### Front-load important information
+
+Place key information early in your content:
+
+**Good:**
+```mdx
+The API key is required for authentication. Generate one in your dashboard settings.
+```
+
+**Poor:**
+```mdx
+To use our API, you'll need several things. First, make sure you have an account. Then, navigate to the settings. Finally, you can generate an API key for authentication.
+```
+
+### Use natural language
+
+Write how users search. If users search "how to deploy", use that phrase in your content:
+
+```mdx
+## How to deploy your documentation
+
+To deploy your documentation, push changes to your connected repository...
+```
+
+## Improve content discoverability
+
+### Create overview pages
+
+Add overview pages for major sections:
+
+```mdx
+---
+title: API reference overview
+description: Complete reference for all API endpoints, authentication, and error handling
+---
+
+Our API provides programmatic access to your documentation. This section covers:
+
+- [Authentication](/api/authentication) - API keys and security
+- [Endpoints](/api/endpoints) - Available API operations
+- [Rate limits](/api/rate-limits) - Usage quotas and limits
+- [Error handling](/api/errors) - Common errors and solutions
+```
+
+### Add cross-references
+
+Link related pages to improve navigation:
+
+```mdx
+<Info>
+  New to Mintlify? Start with the [quickstart guide](/quickstart) before configuring advanced features.
+</Info>
+```
+
+### Use synonyms
+
+Include alternative terms users might search for:
+
+```mdx
+## Environment variables (env vars)
+
+Configure environment variables to customize your deployment...
+```
+
+## Optimize for common queries
+
+### Answer questions directly
+
+Structure content to answer common questions:
+
+```mdx
+## How do I add a custom domain?
+
+To add a custom domain:
+
+1. Go to your dashboard settings
+2. Click "Custom domain"
+3. Enter your domain name
+4. Update your DNS records
+```
+
+### Include troubleshooting
+
+Add troubleshooting sections for common issues:
+
+```mdx
+## Troubleshooting
+
+### Images not loading
+
+If images don't appear:
+- Verify the image path is correct
+- Check that images are committed to Git
+- Ensure file names don't contain spaces
+```
+
+### Document error messages
+
+Include actual error messages users might search for:
+
+```mdx
+## "Module not found" error
+
+If you see `Error: Cannot find module 'mintlify'`:
+
+1. Reinstall the CLI: `npm install -g mintlify`
+2. Clear npm cache: `npm cache clean --force`
+3. Try again
+```
+
+## Technical optimization
+
+### Keep pages focused
+
+Each page should cover one topic thoroughly rather than multiple topics superficially.
+
+**Good structure:**
+```
+/authentication/overview
+/authentication/api-keys
+/authentication/oauth
+/authentication/jwt
+```
+
+**Poor structure:**
+```
+/authentication (covers everything)
+```
+
+### Use descriptive URLs
+
+Page paths affect search relevance:
+
+**Good:**
+```
+/api-playground/openapi-setup
+/deploy/custom-domain
+/troubleshooting/build-errors
+```
+
+**Poor:**
+```
+/page1
+/docs/item
+/misc/other
+```
+
+### Avoid duplicate content
+
+Don't repeat the same information across multiple pages. Instead:
+- Create one authoritative page
+- Link to it from other pages
+- Use snippets for shared content
+
+## Search best practices
+
+### Include code examples
+
+Code examples improve search results for technical queries:
+
+```mdx
+## Install with npm
+
+```bash
+npm install -g mintlify
+```
+
+## Install with pnpm
+
+```bash
+pnpm add -g mintlify
+```
+```
+
+### Add alt text to images
+
+Alt text is indexed by search:
+
+```mdx
+![Dashboard showing deployment status with green checkmark](/images/deployment-success.png)
+```
+
+### Use tables for comparisons
+
+Tables help users find specific information:
+
+```mdx
+| Plan | Rate Limit | Price |
+|------|-----------|-------|
+| Free | 100/min | $0 |
+| Pro | 1000/min | $99/mo |
+| Enterprise | Custom | Custom |
+```
+
+## Monitor search performance
+
+### Check search analytics
+
+Review search queries in your analytics to:
+- Identify common searches
+- Find gaps in documentation
+- Discover confusing terminology
+
+### Test your search
+
+Regularly search for common terms to verify:
+- Relevant pages appear in results
+- Results are ranked appropriately
+- No broken links in results
+
+### Update based on feedback
+
+If users report difficulty finding information:
+1. Review the page's title and description
+2. Add relevant keywords
+3. Improve heading structure
+4. Add cross-references
+
+## Common search issues
+
+### Page not appearing in results
+
+**Causes:**
+- Page not in navigation (hidden pages aren't indexed)
+- Missing or poor title/description
+- Recently published (wait 5-10 minutes for indexing)
+
+**Solutions:**
+- Add page to navigation in `docs.json`
+- Improve frontmatter metadata
+- Redeploy to trigger reindexing
+
+### Wrong pages ranking high
+
+**Causes:**
+- Generic titles across multiple pages
+- Keyword stuffing
+- Duplicate content
+
+**Solutions:**
+- Make titles more specific
+- Use natural language
+- Consolidate duplicate content
+
+### Search showing outdated content
+
+**Causes:**
+- Search index not updated
+- Cached results
+
+**Solutions:**
+- Redeploy your documentation
+- Wait 10-15 minutes for index update
+- Clear browser cache
+
+## Checklist
+
+Use this checklist for each page:
+
+- [ ] Descriptive, unique title
+- [ ] Clear, concise description
+- [ ] Relevant keywords in frontmatter
+- [ ] Clear heading structure (H2, H3)
+- [ ] Important information early in content
+- [ ] Natural language matching user queries
+- [ ] Cross-references to related pages
+- [ ] Code examples with context
+- [ ] Alt text on images
+- [ ] Focused on one topic
+- [ ] Descriptive URL path
diff --git a/troubleshooting.mdx b/troubleshooting.mdx
new file mode 100644
index 000000000..f30f5040e
--- /dev/null
+++ b/troubleshooting.mdx
@@ -0,0 +1,224 @@
+---
+title: Troubleshooting
+description: Common issues and solutions for Mintlify documentation
+---
+
+This guide covers common issues you might encounter when working with Mintlify and how to resolve them.
+
+## Build errors
+
+### Syntax errors in MDX files
+
+**Problem**: Build fails with parsing errors.
+
+**Solution**: Check your MDX files for:
+- Unclosed JSX tags
+- Missing closing braces in component props
+- Invalid frontmatter YAML syntax
+- Special characters that need escaping
+
+Run `mintlify dev` locally to identify the specific file and line causing the error.
+
+### Missing or invalid frontmatter
+
+**Problem**: Pages don't display correctly or build fails.
+
+**Solution**: Ensure every MDX file has valid frontmatter:
+
+```yaml
+---
+title: Your page title
+description: A brief description
+---
+```
+
+Both `title` and `description` are required fields.
+
+### Navigation configuration errors
+
+**Problem**: Build fails with navigation-related errors.
+
+**Solution**: Verify your `docs.json` navigation structure:
+- All page paths reference existing MDX files
+- No duplicate page entries
+- Proper JSON syntax (commas, brackets, quotes)
+- Valid icon names from the Lucide library
+
+## Preview issues
+
+### Local preview not updating
+
+**Problem**: Changes don't appear in `mintlify dev`.
+
+**Solution**:
+1. Stop the dev server (Ctrl+C)
+2. Clear your browser cache
+3. Restart with `mintlify dev`
+4. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
+
+### Images not loading
+
+**Problem**: Images show broken or don't display.
+
+**Solution**:
+- Verify image paths are relative to the MDX file
+- Check that images exist in your repository
+- Ensure image files are committed to Git
+- Use supported formats (PNG, JPG, SVG, GIF, WebP)
+- Check file names don't contain spaces or special characters
+
+### Components not rendering
+
+**Problem**: Mintlify components display as plain text or don't work.
+
+**Solution**:
+- Verify component syntax matches documentation
+- Check for typos in component names (case-sensitive)
+- Ensure props are properly formatted
+- Close all component tags properly
+
+## Deployment issues
+
+### Build succeeds locally but fails in production
+
+**Problem**: `mintlify dev` works but deployment fails.
+
+**Solution**:
+- Check for environment-specific file paths
+- Verify all files are committed and pushed to Git
+- Review deployment logs for specific error messages
+- Ensure `docs.json` is valid JSON (use a JSON validator)
+
+### Changes not appearing after deployment
+
+**Problem**: Deployed site doesn't reflect recent changes.
+
+**Solution**:
+1. Verify changes are pushed to the correct branch
+2. Check deployment status in your Mintlify dashboard
+3. Clear CDN cache if using custom domain
+4. Wait 2-3 minutes for propagation
+5. Hard refresh your browser
+
+### Custom domain not working
+
+**Problem**: Custom domain shows errors or doesn't connect.
+
+**Solution**:
+- Verify DNS records are correctly configured
+- Allow 24-48 hours for DNS propagation
+- Check that CNAME points to your Mintlify subdomain
+- Ensure SSL certificate has been issued (can take up to 24 hours)
+
+## Search issues
+
+### Search not finding pages
+
+**Problem**: Search doesn't return expected results.
+
+**Solution**:
+- Ensure pages are included in navigation (hidden pages aren't indexed)
+- Add descriptive `title` and `description` in frontmatter
+- Include relevant keywords in page content
+- Wait for search index to rebuild after deployment (5-10 minutes)
+
+### Search showing outdated content
+
+**Problem**: Search results show old content.
+
+**Solution**:
+- Redeploy your documentation to trigger reindexing
+- Clear browser cache
+- Wait 10-15 minutes for search index to update
+
+## API documentation issues
+
+### OpenAPI spec not loading
+
+**Problem**: API reference pages don't generate or show errors.
+
+**Solution**:
+- Validate your OpenAPI spec using [Swagger Editor](https://editor.swagger.io/)
+- Ensure the spec file path in `docs.json` is correct
+- Check that the spec is valid JSON or YAML
+- Verify the spec version is supported (OpenAPI 3.0+)
+
+### API playground not working
+
+**Problem**: Try it out feature doesn't work.
+
+**Solution**:
+- Check CORS configuration on your API server
+- Verify authentication setup in `docs.json`
+- Ensure API endpoints are accessible
+- Check browser console for error messages
+
+## Authentication issues
+
+### Users can't access protected docs
+
+**Problem**: Authentication fails or loops.
+
+**Solution**:
+- Verify JWT configuration in `docs.json`
+- Check token expiration settings
+- Ensure authentication endpoint is accessible
+- Review authentication logs in dashboard
+- Test with a fresh browser session (incognito mode)
+
+## Performance issues
+
+### Slow page loads
+
+**Problem**: Documentation loads slowly.
+
+**Solution**:
+- Optimize image sizes (use WebP format, compress images)
+- Reduce number of custom scripts
+- Minimize use of large embedded content
+- Consider lazy loading for heavy components
+
+### Build takes too long
+
+**Problem**: Deployment builds are slow.
+
+**Solution**:
+- Reduce number of pages if possible
+- Optimize image assets
+- Remove unused files from repository
+- Check for circular dependencies in snippets
+
+## Git integration issues
+
+### GitHub/GitLab connection fails
+
+**Problem**: Can't connect repository or deployments don't trigger.
+
+**Solution**:
+- Verify repository permissions (Mintlify needs read access)
+- Check that webhook is properly configured
+- Ensure branch name matches configuration
+- Re-authenticate Git integration in dashboard
+
+### Merge conflicts in docs.json
+
+**Problem**: Navigation changes cause merge conflicts.
+
+**Solution**:
+- Pull latest changes before editing navigation
+- Use web editor for navigation changes when possible
+- Coordinate with team on navigation updates
+- Keep navigation changes in separate commits
+
+## Getting help
+
+If you're still experiencing issues:
+
+1. Check the [status page](https://www.mintlify.com/docs/status) for known incidents
+2. Search [GitHub discussions](https://github.com/orgs/mintlify/discussions) for similar issues
+3. Review deployment logs in your dashboard
+4. [Contact support](https://www.mintlify.com/docs/contact-support) with:
+   - Detailed description of the issue
+   - Steps to reproduce
+   - Error messages or screenshots
+   - Your repository URL (if public)