# SEO Meta Management System

**Last Updated:** 2026-01-10

Complete guide to the centralized SEO meta management system for blog posts, including architecture, usage, and best practices.

## Overview

The SEO Meta Management System provides a centralized way to store, manage, and optimize SEO meta titles and descriptions for all blog posts. It extracts WordPress meta data, stores it in a centralized JSON file, and integrates with the blog meta generator to ensure consistent SEO optimization across all posts.

## Architecture

### Data Flow

```
WordPress Metadata (blog-posts-metadata.json)
    ↓
Extract & Normalize Script (extract-wordpress-meta.php)
    ↓
Centralized SEO Meta Store (v2/data/blog/seo-meta.json)
    ↓
Meta Generator (blog-meta-generator.php)
    ↓
Rendered Meta Tags
```

### File Structure

```
v2/data/blog/
├── seo-meta.json              # Centralized SEO meta data store
└── posts/
    └── {category}/
        └── {slug}.json        # Individual post files (may include meta field)

v2/scripts/blog/
├── extract-wordpress-meta.php      # Extract WordPress meta data
├── update-seo-meta.php             # Update centralized SEO meta store
├── sync-meta-to-posts.php          # Sync meta to individual post files (optional)
├── analyze-seo-meta.php            # Analyze and report on meta quality
└── manage-seo-meta.php             # CLI tool for managing SEO meta

v2/config/
└── blog-meta-generator.php         # Uses centralized meta store
```

## SEO Meta Store Structure

The centralized SEO meta store (`v2/data/blog/seo-meta.json`) has the following structure:

```json
{
  "version": "1.0",
  "last_updated": "2026-01-19T12:00:00Z",
  "posts": {
    "lexikon/leitfaden-zur-finanzbuchhaltung": {
      "title": "Finanzbuchhaltung für Arbeitgeber: Ein Leitfaden | Lexikon - Ordio",
      "description": "Leitfaden zur Finanzbuchhaltung: Hier erfährst du alles Wichtige von den rechtlichen Rahmenbedingungen bis zur Auswahl der richtigen Software.",
      "source": "wordpress",
      "updated_at": "2026-01-19T12:00:00Z",
      "notes": "Optional notes about this meta data"
    }
  }
}
```

### Meta Entry Fields

- **title**: SEO-optimized title (50-60 chars, ends with " - Ordio")
- **description**: SEO-optimized description (150-160 chars)
- **source**: Source of meta data (`wordpress`, `manual`, `custom`)
- **updated_at**: ISO 8601 timestamp of last update
- **notes**: Optional notes about the meta data

## Usage

### CLI Management Tool

The `manage-seo-meta.php` CLI tool provides commands for managing SEO meta data:

#### List All Posts

```bash
php v2/scripts/blog/manage-seo-meta.php list
```

Lists all posts with their SEO meta status.

#### Get Meta for Specific Post

```bash
php v2/scripts/blog/manage-seo-meta.php get lexikon/leitfaden-zur-finanzbuchhaltung
```

Shows SEO meta data for a specific post.

#### Set Custom SEO Meta

```bash
php v2/scripts/blog/manage-seo-meta.php set lexikon/leitfaden-zur-finanzbuchhaltung \
  --title="Custom SEO Title - Ordio" \
  --description="Custom SEO description that is between 150-160 characters long and includes relevant keywords."
```

Sets custom SEO meta for a post. The tool validates length and format before saving.

#### Update from WordPress

```bash
php v2/scripts/blog/manage-seo-meta.php update-from-wordpress
```

Re-extracts WordPress meta data and updates the centralized store. Preserves manual/custom entries.

#### Validate All Meta

```bash
php v2/scripts/blog/manage-seo-meta.php validate
```

Validates all SEO meta data and reports errors and warnings.

#### Analyze Quality

```bash
php v2/scripts/blog/manage-seo-meta.php analyze --output=report.md
```

Generates a comprehensive quality analysis report.

### Direct Script Usage

#### Extract WordPress Meta

```bash
php v2/scripts/blog/extract-wordpress-meta.php [output_file]
```

Extracts and normalizes WordPress meta data. If no output file is specified, outputs to stdout.

#### Update SEO Meta Store

```bash
php v2/scripts/blog/update-seo-meta.php [extracted-wordpress-meta.json]
```

Merges WordPress meta into centralized store. If no input file is specified, extracts directly from WordPress metadata.

#### Sync to Post Files (Optional)

```bash
php v2/scripts/blog/sync-meta-to-posts.php [--dry-run] [--backup]
```

Syncs centralized meta back to individual post JSON files. Creates backup before updating.

#### Analyze Quality

```bash
php v2/scripts/blog/analyze-seo-meta.php [--output=report.md]
```

Analyzes SEO meta quality and generates a report.

## Meta Generator Priority

The blog meta generator (`v2/config/blog-meta-generator.php`) uses the following priority order:

1. **Centralized SEO Meta Store** (`seo-meta.json`) - Highest priority
2. **Post JSON File Meta Field** (`$data['meta']['title']` / `$data['meta']['description']`) - Backward compatibility
3. **Auto-generated Values** - Fallback (from post title/excerpt)

This ensures that WordPress meta data takes priority when available, while maintaining backward compatibility with existing post JSON files.

## Best Practices

### Title Optimization

- **Length**: 50-60 characters (including " - Ordio" suffix)
- **Format**: `{Main Title} | {Category} - Ordio` or `{Main Title} - Ordio`
- **Ending**: Always ends with " - Ordio"
- **Avoid**: Redundant patterns like "| Ordio - Ordio" or "| - Ordio"
- **Keywords**: Include primary keywords near the beginning

**Good Examples:**

- "Finanzbuchhaltung für Arbeitgeber: Ein Leitfaden | Lexikon - Ordio" (59 chars)
- "Schichtplanung effizient gestalten: Tipps & Tools - Ordio" (52 chars)

**Bad Examples:**

- "Finanzbuchhaltung" (too short, missing suffix)
- "Finanzbuchhaltung für Arbeitgeber: Ein Leitfaden | Lexikon | Ordio - Ordio" (redundant)
- "Finanzbuchhaltung | - Ordio" (empty category)

### Description Optimization

- **Length**: 150-160 characters
- **Content**: Benefit-driven, keyword-rich, includes call-to-action
- **Format**: Complete sentences, natural language
- **Keywords**: Include primary and secondary keywords naturally

**Good Examples:**

- "Leitfaden zur Finanzbuchhaltung: Hier erfährst du alles Wichtige von den rechtlichen Rahmenbedingungen bis zur Auswahl der richtigen Software. Jetzt lesen!" (158 chars)

**Bad Examples:**

- "Leitfaden zur Finanzbuchhaltung." (too short)
- "Leitfaden zur Finanzbuchhaltung: Hier erfährst du alles Wichtige von den rechtlichen Rahmenbedingungen bis zur Auswahl der richtigen Software und noch viel mehr darüber hinaus was du wissen musst." (too long)

## Validation

### Title Validation Rules

- Length: 50-60 characters
- Ends with " - Ordio"
- No redundant "| Ordio" patterns
- No empty category separators ("| - Ordio")

### Description Validation Rules

- Length: 150-160 characters
- Not empty
- Contains relevant keywords
- Includes call-to-action when appropriate

## Maintenance

### Regular Tasks

1. **Weekly**: Run `validate` command to check for issues
2. **Monthly**: Run `analyze` command to generate quality report
3. **As Needed**: Use `set` command to update individual posts
4. **After WordPress Updates**: Run `update-from-wordpress` to sync changes

### Adding New Posts

When adding a new blog post:

1. Create the post JSON file in `v2/data/blog/posts/{category}/{slug}.json`
2. Set SEO meta using the CLI tool:
   ```bash
   php v2/scripts/blog/manage-seo-meta.php set {category}/{slug} \
     --title="Optimized Title - Ordio" \
     --description="Optimized description 150-160 chars..."
   ```
3. Validate the meta:
   ```bash
   php v2/scripts/blog/manage-seo-meta.php validate
   ```

### Updating Existing Posts

1. Use the CLI tool to update:
   ```bash
   php v2/scripts/blog/manage-seo-meta.php set {category}/{slug} \
     --title="Updated Title - Ordio" \
     --description="Updated description..."
   ```
2. Or edit `v2/data/blog/seo-meta.json` directly (not recommended)

## Troubleshooting

### Meta Not Showing on Page

1. Check if meta exists in centralized store:
   ```bash
   php v2/scripts/blog/manage-seo-meta.php get {category}/{slug}
   ```
2. Verify meta generator is loading from store (check `blog-meta-generator.php`)
3. Clear any caches

### Validation Errors

1. Run validation to see all issues:
   ```bash
   php v2/scripts/blog/manage-seo-meta.php validate
   ```
2. Fix issues using the `set` command
3. Re-run validation to confirm fixes

### WordPress Meta Not Updating

1. Check WordPress metadata file exists: `docs/data/blog-posts-metadata.json`
2. Run extraction manually:
   ```bash
   php v2/scripts/blog/extract-wordpress-meta.php
   ```
3. Update centralized store:
   ```bash
   php v2/scripts/blog/update-seo-meta.php
   ```

## Related Documentation

- [SEO Optimization Guide](SEO_OPTIMIZATION_GUIDE.md) - Complete SEO/AEO/GEO optimization guide
- [Blog Data Structure](DATA_STRUCTURE_MAPPING.md) - Blog data structure documentation
- [Meta Generator Source](../../../v2/config/blog-meta-generator.php) - Meta generator implementation

## Support

For issues or questions about the SEO Meta Management System:

1. Check validation output: `php v2/scripts/blog/manage-seo-meta.php validate`
2. Review analysis report: `php v2/scripts/blog/manage-seo-meta.php analyze`
3. Check documentation: This file and related docs
4. Review source code: `v2/scripts/blog/manage-seo-meta.php`