# Blog Content Workflow Guide

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

## Overview

This guide explains the complete workflow for managing blog content in the optimized system.

**See Also:**

- `docs/content/CONTENT_CREATION_WORKFLOW_2026.md` - Complete content creation workflow with SISTRIX integration
- `docs/content/CONTENT_UPDATE_WORKFLOW_2026.md` - Content update workflow with quality checks
- `.cursor/rules/content-writing.mdc` - Universal content writing guidelines

## Content Lifecycle

### 1. Create New Post

**Direct JSON Creation:**

1. Create new JSON file: `v2/data/blog/posts/{category}/{slug}.json`
2. Use existing post as template
3. Fill in required fields:
   - `title`, `slug`, `category`, `url`
   - `content.html` (pre-processed HTML)
   - `content.text` (plain text version)
   - `featured_image` (if applicable)
   - `faqs` array (if applicable)
4. Save file

**Note:** WordPress extraction scripts are deprecated (migration complete 2026-01-14). All content is now managed directly via JSON files.

### 2. Content Editing (Existing Posts)

**Direct JSON Editing:**

1. Open: `v2/data/blog/posts/{category}/{slug}.json`
2. Edit `content.html` field directly
3. Save - changes appear immediately

**Optional Cleanup:**

If adding new images/tables:

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

### 3. Content Rendering

**What happens:**

- Load JSON file
- Check cache (file modification time)
- Output pre-processed HTML
- **Zero processing overhead**

## Workflow Examples

### Add New Post

1. Create new JSON file in appropriate category directory:

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

2. Use existing post JSON as template (copy structure)

3. Fill in content:

   - Edit `content.html` with pre-processed HTML
   - Add `content.text` (plain text version)
   - Add `featured_image` if applicable
   - Add `faqs` array if applicable

4. Test rendering in browser:
   ```
   https://www.ordio.com/insights/{category}/{slug}/
   ```

**Note:** WordPress extraction is no longer used. All content is created/edited directly in JSON files.

### Edit Existing Post

1. Open JSON file:

   ```bash
   vim v2/data/blog/posts/lexikon/arbeitszeitmodelle.json
   ```

2. Edit `content.html`:

   ```json
   {
     "content": {
       "html": "<p>Your edited content here...</p>"
     }
   }
   ```

3. Save and test in browser

### Add Image to Post

1. Edit JSON file, add image HTML:

   ```html
   <img src="/insights/bilder/image.webp" alt="Description" />
   ```

2. Run cleanup script:

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

3. Image will be wrapped in lightbox container automatically

### Add FAQ to Post

1. Edit JSON file, add to `faqs` array:

   ```json
   {
     "faqs": [
       {
         "question": "What is this?",
         "answer": "<p>This is the answer...</p>"
       }
     ]
   }
   ```

2. FAQs are rendered separately by `BlogFAQ.php` component

### Bulk Update All Posts

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

**Use cases:**

- Apply new processing rules
- Clean up WordPress artifacts
- Update image wrapping
- Re-sanitize content

## Content Structure

### Pre-Processed HTML

Content HTML is fully processed:

```html
<!-- Images are wrapped -->
<div
  class="blog-image-lightbox-trigger"
  data-lightbox-src="/insights/bilder/image.webp"
  x-on:click="openImageLightboxFromElement($el)"
>
  <img src="/insights/bilder/image.webp" alt="..." />
</div>

<!-- Tables are wrapped -->
<div class="table-breakout-wrapper">
  <table>
    ...
  </table>
</div>

<!-- HTML is sanitized -->
<p>Clean content...</p>
```

### FAQs Structure

FAQs are stored separately:

```json
{
  "faqs": [
    {
      "question": "Question text",
      "answer": "<p>Answer HTML...</p>"
    }
  ]
}
```

## Best Practices

### 1. Edit JSON Directly

✅ **Do:** Edit `content.html` field directly in JSON
❌ **Don't:** Try to process HTML at render time

### 2. Run Cleanup When Needed

✅ **Do:** Run cleanup script when adding images/tables
❌ **Don't:** Run cleanup on every edit (unnecessary)

### 3. Test After Changes

✅ **Do:** Test rendering after major changes
✅ **Do:** Run performance tests periodically

### 4. Preserve Structure

✅ **Do:** Keep FAQs in separate array
✅ **Do:** Maintain JSON structure
❌ **Don't:** Embed FAQs in content HTML

## Performance Considerations

### Render Time

- **Current:** 0.02ms per post
- **Target:** < 50ms ✅
- **Optimization:** All processing at extraction time

### Cache Invalidation

JSON files are cached with file modification time:

- Cache invalidates automatically when file changes
- No manual cache clearing needed
- File modification time checked on each request

### OPcache

For additional PHP performance:

1. Configure OPcache (see `docs/development/setup/OPCACHE_CONFIGURATION.md`)
2. Restart PHP-FPM after configuration
3. Monitor OPcache status

## Troubleshooting

### Content Not Updating

1. Check file modification time
2. Clear browser cache
3. Verify JSON file saved correctly
4. Check file permissions

### Images Not Wrapping

1. Run cleanup script on post
2. Check image is not inside `<a>` tag
3. Verify image structure in HTML

### Performance Degradation

1. Run performance test
2. Check OPcache status
3. Verify JSON caching working
4. Check for large JSON files

## Testing

### Performance Test

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

**Checks:**

- Render time
- Content structure
- WordPress artifacts

### Content Rendering Test

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

**Checks:**

- Content renders correctly
- FAQs separate
- HTML valid

### Comprehensive Test

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

**Checks:**

- Images wrapped
- Links working
- Content structure
- Rendering success

## References

- `docs/content/blog/BLOG_QUICK_REFERENCE.md` - Quick reference
- `docs/content/blog/BLOG_PERFORMANCE_OPTIMIZATION.md` - Performance guide
- `docs/content/blog/BLOG_SYSTEM_SIMPLIFICATION_GUIDE.md` - System guide