# Template Content Edit Workflow

**Last Updated:** 2026-03-23

How to edit template content blocks. Parallel to [BLOG_CONTENT_EDIT_WORKFLOW.md](../../content/blog/BLOG_CONTENT_EDIT_WORKFLOW.md) (blog uses `content-draft.html` + `update-post-content.php`; templates use `content.md` + `sync-template-content-blocks.php` — comparison table in that doc).

## Rule: Edit Content Files, Not JSON

**Edit `content/content.md` (one file per page), then run sync.** Do not edit `content-blocks.json` directly.

Direct JSON edits risk:

- Escaping issues (`\/` vs `/`)
- Unicode corruption (German umlauts, quotes)
- Sync overwriting your changes

## How to Edit Content

### 0. Check Competitive Depth (Before Editing)

Check `template-data/{id}/data/competitive-depth-analysis.md` for the target word count before editing. Use this as your goal for expansion or new content.

### 1. Edit Content File

Content lives in one file per template:

```
docs/systems/templates/template-data/{template_id}/content/
└── content.md
```

Blocks are separated by `--- block-N ---` and each has YAML frontmatter + HTML body. See [BLOCK_CONTENT_FORMAT.md](_templates/BLOCK_CONTENT_FORMAT.md).

### 2. Run Sync

After editing, sync content to JSON:

```bash
# Single template
php v2/scripts/templates/sync-template-content-blocks.php --template=dienstplan-excel-vorlage

# All templates with content/
php v2/scripts/templates/sync-template-content-blocks.php --all

# Dry-run (preview, no write)
php v2/scripts/templates/sync-template-content-blocks.php --template=id --dry-run
```

### 3. Validate

After edits, run audit and validation:

```bash
# Audit: word count vs target, keywords, links, block types (uses competitive-depth targets)
python3 v2/scripts/templates/audit-template-content-blocks.py --template=id
# or --all for all templates

# Validate: min/max words per template, no empty content, valid types
php v2/scripts/templates/validate-template-content-blocks.php --all
```

See [CONTENT_TARGETS_REFERENCE.md](CONTENT_TARGETS_REFERENCE.md) for how targets are derived.

## Adding a New Block

1. Add a new section to `content/content.md` with `--- block-N ---` separator, frontmatter + HTML body
2. Run sync
3. Verify on template page

## Migrating from JSON to Content File

If you have `content-blocks.json` but no `content/content.md`:

```bash
php v2/scripts/templates/sync-template-content-blocks.php --template=id --export
```

This creates `content.md` from the JSON. Edit content.md and run sync (without --export) to update JSON.

## Keyword Integration

- Add `keywords: ["keyword1", "keyword2"]` to block frontmatter
- See [KEYWORD_MAPPING.md](KEYWORD_MAPPING.md) for SISTRIX keyword-to-section mapping
- Primary keyword in H1/H2; secondary in first paragraph; long-tail in examples/callouts

## Internal Links

- Use canonical URLs: `/schichtplan`, `/arbeitszeiterfassung`
- Minimum 2–3 internal links per template
- See [CANONICAL_URLS_AND_LINKING.md](../../development/CANONICAL_URLS_AND_LINKING.md)

## References

- [TEMPLATE_CONTENT_BLOCKS_GUIDE.md](TEMPLATE_CONTENT_BLOCKS_GUIDE.md) – Block types, design tokens
- [TEMPLATE_CONTENT_WORKFLOW.md](TEMPLATE_CONTENT_WORKFLOW.md) – Master workflow