mintel.me/apps/web/EMBED_USAGE_GUIDE.md

# Embed Components Usage Guide

## Overview
Your blog now supports rich content embedding from YouTube, Twitter/X, and other platforms with **full styling control** and **build-time generation**.

## Components Available

### 1. YouTubeEmbed
**Location:** `src/components/YouTubeEmbed.astro`

**Features:**
- Build-time generation (no client-side API calls)
- Full styling control via CSS variables
- Lazy loading with Intersection Observer
- Multiple style variations
- Responsive aspect ratios

**Usage:**
```astro
---
import YouTubeEmbed from '../components/YouTubeEmbed.astro';
---

<YouTubeEmbed 
  videoId="dQw4w9WgXcQ"
  title="My Video"
  className="my-custom-class"
  aspectRatio="56.25%"
  style="minimal"
/>
```

**Props:**
- `videoId` (required) - YouTube video ID
- `title` (optional) - Video title for accessibility
- `className` (optional) - Custom CSS classes
- `aspectRatio` (optional) - Default "56.25%" (16:9)
- `style` (optional) - 'default' | 'minimal' | 'rounded' | 'flat'

**Styling Control:**
```css
/* Override CSS variables */
.youtube-embed {
  --aspect-ratio: 56.25%;
  --bg-color: #000000;
  --border-radius: 8px;
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
}

/* Use data attributes for variations */
.youtube-embed[data-style="minimal"] { /* ... */ }
.youtube-embed[data-aspect="square"] { /* ... */ }
```

### 2. TwitterEmbed
**Location:** `src/components/TwitterEmbed.astro`

**Features:**
- Fetches tweet data at build time using Twitter oEmbed API
- Fallback to simple link if API fails
- Theme support (light/dark)
- Alignment options
- Runtime widget loading for enhanced display

**Usage:**
```astro
---
import TwitterEmbed from '../components/TwitterEmbed.astro';
---

<TwitterEmbed 
  tweetId="1234567890123456789"
  theme="dark"
  className="my-tweet"
  align="center"
/>
```

**Props:**
- `tweetId` (required) - Tweet ID from URL
- `theme` (optional) - 'light' | 'dark'
- `className` (optional) - Custom CSS classes
- `align` (optional) - 'left' | 'center' | 'right'

**Note:** Requires internet access during build to fetch tweet data.

### 3. GenericEmbed
**Location:** `src/components/GenericEmbed.astro`

**Features:**
- Universal oEmbed support
- Auto-detects provider
- Fallback for unsupported platforms
- Type-specific styling (video, article, rich)

**Usage:**
```astro
---
import GenericEmbed from '../components/GenericEmbed.astro';
---

<GenericEmbed 
  url="https://vimeo.com/123456789"
  type="video"
  className="my-embed"
  maxWidth="800px"
/>
```

**Props:**
- `url` (required) - Full URL to embed
- `type` (optional) - 'video' | 'article' | 'rich'
- `className` (optional) - Custom CSS classes
- `maxWidth` (optional) - Container max width

**Supported Providers:**
- YouTube (via oEmbed)
- Vimeo (via oEmbed)
- Twitter/X (via oEmbed)
- CodePen (via oEmbed)
- GitHub Gists (via oEmbed)

## Integration Examples

### In Blog Posts (src/pages/blog/[slug].astro)
```astro
---
import YouTubeEmbed from '../components/YouTubeEmbed.astro';
import TwitterEmbed from '../components/TwitterEmbed.astro';
import GenericEmbed from '../components/GenericEmbed.astro';
---

{post.slug === 'my-post' && (
  <>
    <h2>YouTube Example</h2>
    <YouTubeEmbed videoId="dQw4w9WgXcQ" style="minimal" />
    
    <h2>Twitter Example</h2>
    <TwitterEmbed tweetId="1234567890123456789" theme="dark" />
    
    <h2>Vimeo Example</h2>
    <GenericEmbed url="https://vimeo.com/123456789" type="video" />
  </>
)}
```

### In MDX Content
```mdx
import { YouTubeEmbed, TwitterEmbed } from '../components/Embeds';

# My Blog Post

Here's a YouTube video:

<YouTubeEmbed videoId="dQw4w9WgXcQ" style="rounded" />

And a tweet:

<TwitterEmbed tweetId="1234567890123456789" />
```

## Custom Styling Examples

### Minimal Blog Style
```css
/* In your global.css */
.youtube-embed[data-style="minimal"] {
  --border-radius: 4px;
  --shadow: none;
  --bg-color: #1a1a1a;
}

.twitter-embed {
  --border-radius: 6px;
  --bg-color: #f8fafc;
}

/* Hover effects */
.embed-wrapper:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}
```

### Dark Mode Support
```css
/* Dark mode adjustments */
@media (prefers-color-scheme: dark) {
  .youtube-embed {
    --bg-color: #000000;
    --border-color: #334155;
  }
  
  .twitter-embed[data-theme="dark"] {
    --bg-color: #1e293b;
  }
}
```

### Custom Width & Alignment
```astro
<YouTubeEmbed 
  videoId="dQw4w9WgXcQ"
  className="max-w-2xl mx-auto"
/>
```

## Performance Benefits

1. **Build-Time Generation** - All embeds are fetched at build time
2. **Zero Client JS** - No external API calls on page load
3. **Lazy Loading** - Iframes load only when visible
4. **CDN Compatible** - Works with any static hosting
5. **SEO Friendly** - Static HTML content

## Troubleshooting

### Twitter Embed Not Loading
- Check internet connection during build
- Verify tweet ID is correct
- Check Twitter API status
- Fallback link will be shown

### YouTube Embed Issues
- Verify video ID is correct
- Video must be public/unlisted
- Check iframe restrictions

### Generic Embed Failures
- Provider must support oEmbed
- Some providers require authentication
- Fallback to simple link provided

## Migration from Paid Services

If you were using services like Embedly or Iframely:

1. **Replace imports:**
   ```diff
   - import Embedly from 'embedly-react';
   + import YouTubeEmbed from '../components/YouTubeEmbed.astro';
   ```

2. **Update props:**
   ```diff
   - <Embedly url={videoUrl} />
   + <YouTubeEmbed videoId="abc123" />
   ```

3. **Customize styling** using CSS variables

## Next Steps

1. Test components in your development environment
2. Add embeds to existing blog posts
3. Customize styling to match your theme
4. Consider adding more providers (Instagram, TikTok, etc.)

All components are **free**, **self-hosted**, and give you **complete control** over styling and behavior.