wip
This commit is contained in:
259
EMBED_USAGE_GUIDE.md
Normal file
259
EMBED_USAGE_GUIDE.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user