# Blog Embed Maintenance Guide

**Last Updated:** 2026-01-09

Guide for maintaining embedded content in blog posts, troubleshooting issues, and adding new embed types.

## Quick Reference

### Audit Embeds

```bash
python3 scripts/blog/audit-embeds.py
```

### Sync Embeds to Post Files

```bash
python3 scripts/blog/sync-embeds-to-posts.py
```

### Test Embeds

```bash
python3 scripts/blog/test-embeds.py
```

## Adding New Embed Types

### Step 1: Update Domain Whitelist

Edit `v2/config/blog-template-helpers.php`, find `$allowed_embed_domains` array (around line 900), add new domain:

```php
$allowed_embed_domains = [
    // ... existing domains ...
    'new-embed-domain.com',
    'www.new-embed-domain.com',
];
```

### Step 2: Test Sanitization

The sanitization function will automatically allow iframes/scripts from whitelisted domains. Test with:

```php
$test_html = '<iframe src="https://new-embed-domain.com/embed/123"></iframe>';
$sanitized = sanitizeHtmlOutput($test_html);
// Should preserve iframe if domain is whitelisted
```

### Step 3: Add CSS (if needed)

If new embed type needs custom styling, add to `v2/css/blog-post.css`:

```css
.post-content-inner .new-embed-type {
  /* Custom styles */
}
```

### Step 4: Update Documentation

- Update `docs/content/blog/EMBED_HANDLING_GUIDE.md`
- Update this maintenance guide
- Update `.cursor/rules/blog-templates.mdc`

## Troubleshooting

### Embed Not Displaying

**Checklist**:

1. **Extraction**: Is embed in `docs/data/blog-posts-content-full.json`?

   ```bash
   grep -i "embed-domain" docs/data/blog-posts-content-full.json
   ```

2. **Post File**: Is embed in individual post JSON file?

   ```bash
   cat v2/data/blog/posts/{category}/{slug}.json | grep -i "iframe\|script"
   ```

3. **Sanitization**: Is domain whitelisted?

   - Check `v2/config/blog-template-helpers.php` line ~900
   - Verify domain matches exactly (case-insensitive)

4. **Component**: Is PostContent preserving embed?

   - Check `v2/components/blog/PostContent.php`
   - Verify embed blocks aren't being removed

5. **Browser**: Check browser console for errors
   - Blocked content warnings
   - CORS errors
   - Network errors

### Embed Blocked by Sanitization

**Symptoms**: Embed appears as HTML comment `<!-- Blocked unsafe embed: ... -->`

**Solutions**:

- Add domain to whitelist
- Check URL format (must be `https://` or `http://`)
- Remove `javascript:` protocol if present
- Verify domain spelling

### Responsive Issues

**Symptoms**: Embed overflows container or doesn't scale on mobile

**Solutions**:

- Verify CSS is loaded (`blog-base.min.css` + `blog-post.min.css`)
- Check aspect ratio classes are present (`wp-embed-aspect-16-9`)
- Ensure iframe has width/height attributes
- Test with browser dev tools mobile view

### Podigee Player Not Loading

**Symptoms**: Podcast player doesn't appear

**Solutions**:

- Verify script src is correct
- Check `data-configuration` attribute is present
- Verify Podigee domain is whitelisted
- Check browser console for script loading errors
- Ensure script tag is not being stripped

## Common Issues

### WordPress Embed Blocks Not Preserved

**Issue**: WordPress `wp-block-embed` containers are removed

**Solution**: PostContent component should preserve these. Check:

- XPath query excludes embed blocks from removal
- Embed wrapper divs are not removed
- Iframe elements are preserved

### Multiple Embeds on Same Page

**Issue**: Only first embed displays

**Solution**: All embeds should display. Check:

- Each embed has unique src
- No duplicate IDs
- CSS doesn't hide subsequent embeds

### Embeds Breaking Layout

**Issue**: Embed causes page layout shift

**Solution**:

- Ensure aspect ratio CSS is applied
- Add explicit width/height to iframe
- Use responsive embed containers

## Maintenance Tasks

### Monthly Audit

Run embed audit to check for:

- Broken embed URLs
- New embed types that need whitelisting
- Posts with missing embeds

```bash
python3 scripts/blog/audit-embeds.py
```

### After WordPress Updates

If WordPress adds new embed types:

1. Check extraction script preserves them
2. Add domain to whitelist if needed
3. Test extraction and rendering
4. Update documentation

### After Content Updates

If posts are updated with new embeds:

1. Re-extract content if needed
2. Sync embeds to post files
3. Test rendering
4. Validate URLs

## Testing Checklist

Before deploying embed changes:

- [ ] All existing embeds still work
- [ ] New embed type displays correctly
- [ ] Responsive behavior works (mobile/tablet/desktop)
- [ ] Sanitization blocks unsafe embeds
- [ ] No console errors
- [ ] Performance acceptable (no significant slowdown)
- [ ] Accessibility (keyboard navigation, screen readers)

## Related Documentation

- [Embed Handling Guide](EMBED_HANDLING_GUIDE.md) - Complete embed documentation
- [Content Extraction Guide](CONTENT_EXTRACTION_GUIDE.md) - Extraction process
- [Migration Requirements](MIGRATION_REQUIREMENTS.md) - Migration requirements