# Blog System Quick Reference Guide

**Last Updated:** 2026-01-14

## Quick Overview

The blog system is optimized for maximum performance with zero render-time processing. All content is pre-processed at extraction time and stored ready-to-render in JSON files.

## Performance

- **Render time:** 0.02ms per post (99.6% reduction)
- **PostContent.php:** 34 lines (zero processing)
- **Processing:** All done at extraction time

## Manual Editing Workflow

### Edit a Blog Post

1. **Open JSON file:**

   ```bash
   v2/data/blog/posts/{category}/{slug}.json
   ```

2. **Edit content directly:**

   - Modify `content.html` field
   - Add/edit FAQs in `faqs` array
   - Update metadata as needed

3. **Save and test:**
   - Changes appear immediately
   - No processing needed
   - Test in browser

### Add Images/Tables

If adding new images or tables, optionally run:

```bash
python3 scripts/blog/clean-existing-posts.py --category={category} --post={slug}
```

This will:

- Wrap new images in lightbox containers
- Wrap new tables in breakout containers
- Sanitize HTML content

## File Structure

```
v2/data/blog/posts/
├── lexikon/
│   ├── arbeitszeitmodelle.json
│   └── ...
├── ratgeber/
│   └── ...
└── inside-ordio/
    └── ...

v2/components/blog/
├── PostContent.php      # 34 lines - just outputs HTML
├── PostHeader.php
├── PostCard.php
└── ...

scripts/blog/
├── extract-content.py           # DEPRECATED: WordPress extraction (migration complete)
├── clean-existing-posts.py      # Clean existing posts
└── test-performance.php         # Performance testing
```

## JSON Structure

```json
{
  "slug": "post-slug",
  "title": "Post Title",
  "category": "lexikon",
  "url": "/insights/lexikon/post-slug/",
  "content": {
    "html": "<p>Pre-processed HTML...</p>",
    "text": "Plain text...",
    "word_count": 1214
  },
  "faqs": [
    {"question": "...", "answer": "..."}
  ],
  "images": [...],
  "internal_links": [...]
}
```

## Common Tasks

### Re-process All Posts

```bash
python3 scripts/blog/clean-existing-posts.py --all
```

### Re-process Single Post

```bash
python3 scripts/blog/clean-existing-posts.py --category=lexikon --post=arbeitszeitmodelle
```

### Test Performance

```bash
php scripts/blog/test-performance.php
```

### Test Content Rendering

```bash
php scripts/blog/test-content-rendering.php
```

### Comprehensive Test

```bash
php scripts/blog/test-comprehensive.php
```

## Content Processing

All content is pre-processed at extraction time:

- ✅ **Images** - Wrapped in lightbox containers
- ✅ **Tables** - Wrapped in breakout containers
- ✅ **HTML** - Sanitized (XSS prevention)
- ✅ **WordPress artifacts** - Removed

## Performance Targets

- ✅ Render time: < 50ms (achieved: 0.02ms)
- ✅ Zero DOMDocument usage
- ✅ Zero render-time processing
- ✅ WordPress artifacts removed

## Troubleshooting

### Content Not Rendering

1. Check JSON file exists
2. Verify `content.html` field is present
3. Check file permissions
4. Run content rendering test

### Images Not Wrapping

1. Run cleanup script on post
2. Check image is not inside `<a>` tag
3. Verify image has `src` attribute

### Performance Issues

1. Run performance test
2. Check OPcache status
3. Verify JSON caching is working
4. Check file modification times

## References

- `docs/content/blog/BLOG_PERFORMANCE_OPTIMIZATION.md` - Performance guide
- `docs/content/blog/BLOG_SYSTEM_SIMPLIFICATION_GUIDE.md` - System guide
- `docs/development/setup/OPCACHE_CONFIGURATION.md` - OPcache setup
- `.cursor/rules/blog-templates.mdc` - Template patterns