# Blog Production Workflow Guide

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

Complete guide for managing blog content in production. WordPress is no longer used - all content is managed directly via JSON files.

**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
- `docs/content/CONTENT_WRITING_BEST_PRACTICES_2026.md` - Content writing best practices

## Overview

The blog system is fully migrated from WordPress to PHP static pages. All content is stored in JSON files and served through PHP templates. WordPress extraction is no longer needed or used.

**Content Writing Guidelines:**

When creating or updating blog content, follow these guidelines:
- Human-first content principles (see `docs/content/CONTENT_WRITING_BEST_PRACTICES_2026.md`)
- Natural language writing (avoid AI content tells)
- SEO-optimized natural content (integrate keywords naturally)
- Proper content structure (header hierarchy, formatting)
- Meta tag optimization (see `docs/content/META_TAGS_OPTIMIZATION_GUIDE.md`)

## Content Management

### Edit Existing Post

1. **Open JSON file:**
   ```bash
   v2/data/blog/posts/{category}/{slug}.json
   ```

2. **Edit content directly:**
   - Modify `content.html` field (pre-processed HTML)
   - Update `content.text` field (plain text version)
   - Edit `faqs` array if needed
   - Update metadata fields as needed

3. **Save and test:**
   - Changes appear immediately
   - Test in browser: `https://www.ordio.com/insights/{category}/{slug}/`

### Add New Post

1. **Create new JSON file:**
   ```bash
   v2/data/blog/posts/{category}/{new-slug}.json
   ```

2. **Use existing post as template:**
   - Copy structure from similar post
   - Update all fields:
     - `slug`: URL-friendly slug
     - `title`: Post title
     - `category`: `lexikon`, `ratgeber`, or `inside-ordio`
     - `url`: `/insights/{category}/{slug}/`
     - `content.html`: Pre-processed HTML content
     - `content.text`: Plain text version
     - `featured_image`: Image data object (if applicable)
     - `faqs`: Array of FAQ objects (if applicable)

3. **Add required metadata:**
   - `publication_date`: ISO 8601 format (e.g., `2026-01-14T10:00:00+01:00`)
   - `modified_date`: ISO 8601 format
   - `author`: Author object (if applicable)
   - `excerpt`: Post excerpt (140 chars recommended)

4. **Test rendering:**
   - Visit: `https://www.ordio.com/insights/{category}/{slug}/`
   - Verify content displays correctly
   - Check SEO meta tags
   - Validate schema markup

### Image Management

**Adding Images:**

1. **Upload image to local storage:**
   ```bash
   /v2/img/insights/filename.webp
   ```

2. **Reference in JSON:**
   ```html
   <img src="/insights/bilder/filename.webp" alt="Description" width="800" height="600" />
   ```

3. **For featured images, add to JSON:**
   ```json
   "featured_image": {
     "src": "/insights/bilder/filename.webp",
     "alt": "Description",
     "width": 800,
     "height": 600,
     "srcset": [
       {"src": "/insights/bilder/filename-640w.webp", "width": 640},
       {"src": "/insights/bilder/filename-1280w.webp", "width": 1280}
     ]
   }
   ```

**Image Requirements:**
- Format: WebP (preferred) or JPG/PNG
- Storage: `/v2/img/insights/`
- Public URL: `/insights/bilder/`
- Responsive: Include srcset for multiple sizes
- Alt text: Always required for accessibility

### FAQ Management

**Add FAQs to Post:**

1. **Edit JSON file:**
   ```json
   "faqs": [
     {
       "question": "What is...?",
       "answer": "Answer text here..."
     }
   ]
   ```

2. **FAQ Best Practices:**
   - 3-8 FAQs per post (optimal)
   - Answers: 40-80 words
   - Include target keywords naturally
   - Answer user intent questions
   - Reference Ordio once per FAQ (when relevant)

### Content Cleanup (Optional)

If adding new images or tables, optionally run cleanup:

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

This will:
- Wrap images in lightbox containers
- Wrap tables in breakout containers
- Sanitize HTML content

## Workflow Examples

### Example: Edit Post Title

1. Open: `v2/data/blog/posts/lexikon/arbeitszeitmodelle.json`
2. Change: `"title": "New Title"`
3. Save file
4. Test: Visit `/insights/lexikon/arbeitszeitmodelle/`

### Example: Add FAQ to Post

1. Open: `v2/data/blog/posts/ratgeber/dienstplan-erstellen.json`
2. Add to `faqs` array:
   ```json
   {
     "question": "How do I create a shift plan?",
     "answer": "You can create a shift plan using Ordio's digital shift planning tool..."
   }
   ```
3. Save file
4. FAQ appears automatically on post page

### Example: Update Post Content

1. Open JSON file
2. Edit `content.html` field directly
3. Update `content.text` field (plain text version)
4. Update `modified_date` to current date
5. Save and test

## Backup Procedures

**Before Making Changes:**

1. **Create snapshot backup:**
   ```bash
   python3 scripts/blog/backup-blog-content.py --manual
   ```

2. **Verify backup created:**
   ```bash
   python3 scripts/blog/validate-backup.py docs/backups/blog-snapshots/{timestamp}
   ```

**Restore from Backup:**

```bash
python3 scripts/blog/restore-from-snapshot.py docs/backups/blog-snapshots/{timestamp}
```

## Validation

**Validate Post Structure:**

```bash
php v2/scripts/blog/validate-blog-content.php
```

**Validate Images:**

```bash
python3 v2/scripts/blog/validate-images-links.py
```

**Validate Links:**

```bash
php v2/scripts/blog/validate-link-quality.php
```

## Important Notes

### WordPress No Longer Used

- ❌ No WordPress extraction needed
- ❌ No WordPress CMS access required
- ❌ No WordPress API calls
- ✅ All content managed via JSON files
- ✅ Direct editing workflow

### Content Format

- **HTML:** Pre-processed at creation time (no render-time processing)
- **Images:** Stored locally in `/v2/img/insights/`
- **URLs:** Use `/insights/bilder/` for images
- **Dates:** ISO 8601 format required

### Performance

- **Render Time:** <0.02ms per post
- **Zero Processing:** All content pre-processed
- **Fast Loading:** Static JSON files
- **Optimized:** Images lazy-loaded, responsive

## Related Documentation

- `docs/content/blog/BLOG_QUICK_REFERENCE.md` - Quick reference
- `docs/content/blog/MIGRATION_COMPLETION_REPORT_2026-01-14.md` - Migration status
- `docs/content/blog/TROUBLESHOOTING_GUIDE.md` - Troubleshooting
- `.cursor/rules/blog-templates.mdc` - Template patterns

## Support

For questions or issues:
- Check troubleshooting guide
- Review migration completion report
- Verify JSON structure matches existing posts
- Test in browser before deploying