diff --git a/ai/ads.mdx b/ai/ads.mdx
new file mode 100644
index 000000000..afe9d0843
--- /dev/null
+++ b/ai/ads.mdx
@@ -0,0 +1,231 @@
+---
+title: AI ads
+description: Automatically generate and optimize promotional content with AI-powered advertising
+---
+
+# AI ads
+
+Use AI ads to automatically generate contextually relevant promotional content for your documentation. The AI analyzes your content and user behavior to create targeted advertisements that enhance engagement without disrupting the reading experience.
+
+## Getting started
+
+### Prerequisites
+
+- Active Mintlify account with AI features enabled
+- Documentation site with at least 10 published pages
+- Analytics tracking configured
+
+### Enable AI ads
+
+1. Open your Mintlify dashboard
+2. Navigate to **Settings** → **AI Features**
+3. Toggle **AI Ads** to enabled
+4. Click **Save changes**
+
+```json
+{
+  "ai": {
+    "ads": {
+      "enabled": true,
+      "placement": ["sidebar", "footer"],
+      "frequency": "medium"
+    }
+  }
+}
+```
+
+## Configuration
+
+### Basic setup
+
+Configure AI ads in your `mint.json` file:
+
+```json
+{
+  "ai": {
+    "ads": {
+      "enabled": true,
+      "placement": ["sidebar", "inline", "footer"],
+      "frequency": "low",
+      "targeting": {
+        "contentBased": true,
+        "behaviorBased": true
+      }
+    }
+  }
+}
+```
+
+### Placement options
+
+| Placement | Description | Best for |
+|-----------|-------------|----------|
+| `sidebar` | Right sidebar of documentation pages | Non-intrusive promotion |
+| `inline` | Between content sections | High engagement |
+| `footer` | Bottom of each page | Subtle promotion |
+| `banner` | Top of page header | Important announcements |
+
+### Frequency settings
+
+- `low` - Show ads on 20% of page views
+- `medium` - Show ads on 50% of page views  
+- `high` - Show ads on 80% of page views
+
+## Ad types
+
+### Contextual ads
+
+AI-generated ads based on the current page content and user reading patterns.
+
+```json
+{
+  "ai": {
+    "ads": {
+      "contextual": {
+        "enabled": true,
+        "relevanceThreshold": 0.8,
+        "maxAdsPerPage": 2
+      }
+    }
+  }
+}
+```
+
+### Product recommendations
+
+Smart suggestions for related products, features, or services.
+
+```json
+{
+  "ai": {
+    "ads": {
+      "recommendations": {
+        "enabled": true,
+        "categories": ["features", "integrations", "upgrades"],
+        "personalization": true
+      }
+    }
+  }
+}
+```
+
+### Content promotion
+
+Promote relevant documentation sections or resources to improve discoverability.
+
+```json
+{
+  "ai": {
+    "ads": {
+      "contentPromotion": {
+        "enabled": true,
+        "promoteRelated": true,
+        "promotePopular": true
+      }
+    }
+  }
+}
+```
+
+## Customization
+
+### Styling
+
+Match ads to your documentation theme:
+
+```json
+{
+  "ai": {
+    "ads": {
+      "styling": {
+        "theme": "auto",
+        "borderRadius": "8px",
+        "shadow": "subtle",
+        "animation": "fade"
+      }
+    }
+  }
+}
+```
+
+### Targeting
+
+Define audience segments and targeting criteria:
+
+```json
+{
+  "ai": {
+    "ads": {
+      "targeting": {
+        "userSegments": ["new_users", "power_users"],
+        "pageCategories": ["getting-started", "advanced"],
+        "excludePages": ["/internal/*"]
+      }
+    }
+  }
+}
+```
+
+## Analytics and optimization
+
+### Performance metrics
+
+Track ad performance in your dashboard:
+
+- **Click-through rate (CTR)** - Percentage of users who click ads
+- **Engagement rate** - Time spent viewing ad content
+- **Conversion rate** - Users who complete desired actions
+- **Revenue attribution** - Sales generated from ad clicks
+
+### A/B testing
+
+Test different ad configurations:
+
+```json
+{
+  "ai": {
+    "ads": {
+      "testing": {
+        "enabled": true,
+        "variants": [
+          {"placement": "sidebar", "frequency": "low"},
+          {"placement": "inline", "frequency": "medium"}
+        ],
+        "splitRatio": 0.5
+      }
+    }
+  }
+}
+```
+
+### Optimization tips
+
+- Monitor CTR weekly and adjust frequency if below 2%
+- Test different placements for 2 weeks before deciding
+- Use contextual ads for technical content, recommendations for feature pages
+- Exclude ads from critical user flows like onboarding
+
+## Best practices
+
+### Content relevance
+- Ensure ads match the page topic and user intent
+- Use AI confidence scores to filter low-relevance ads
+- Regularly review and update targeting criteria
+
+### User experience
+- Limit to 2 ads per page maximum
+- Use subtle animations and transitions
+- Provide clear "dismiss" options for users
+- Test on mobile devices regularly
+
+### Performance monitoring
+- Set up alerts for CTR drops below 1.5%
+- Review analytics monthly for optimization opportunities
+- A/B test new placements quarterly
+- Monitor page load times to ensure ads don't slow performance
+
+### Compliance
+- Follow advertising disclosure requirements
+- Respect user privacy preferences
+- Comply with GDPR, CCPA, and other regulations
+- Provide opt-out mechanisms for users
\ No newline at end of file
diff --git a/docs.json b/docs.json
index b62a3820b..cac7cce93 100644
--- a/docs.json
+++ b/docs.json
@@ -57,6 +57,7 @@
               "ai/contextual-menu",
               "ai/model-context-protocol",
               "ai/markdown-export",
+              "ai/ads",
               "guides/geo",
               "guides/claude-code",
               "guides/cursor",