# Template Content Workflow

**Last Updated:** 2026-04-01

Master workflow for template page content optimization. Latest completion: stundennachweis-vorlage (2026-03-26). Parallel to [BLOG_POST_IMPROVEMENT_PROCESS.md](../../content/blog/BLOG_POST_IMPROVEMENT_PROCESS.md).

**Data-first baseline (existing URLs):** [PAGE_IMPROVEMENT_DATA_PLAYBOOK.md](../../content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md) — refresh GSC/GA and template `data/performance-gsc.json` where applicable before large content or meta changes.

**System context:** See [TEMPLATE_SYSTEM_OVERVIEW.md](TEMPLATE_SYSTEM_OVERVIEW.md) — only 7 templates are published in production.

## Overview

1. **Data collection** – SISTRIX keywords, PAA, competitor analysis, GSC, faq-research, competitive-depth
2. **Phase 1.5** – `validate-template-competitor-data-completeness.php`; Serper MCP for primary keyword (mandatory); Firecrawl MCP for sparse competitors
3. **SERP analysis** – Manual browser review (min 30 min), SERP_ANALYSIS.md, CONTENT_OUTLINE.md (Serper MCP mandatory)
4. **Phase gate** – Run `validate-template-improvement-readiness.php` before content creation
5. **Section briefs** – Run `generate-template-section-briefs.php`; overlap check before content
6. **Content blocks** – `generate-template-content-blocks.php` (optional `--use-ai`); edit content.md per outline; sync to content-blocks.json
7. **FAQ workflow** – faq-research → questions → answers → template-faqs.json; run `check-template-block-faq-overlap.php` before add-template-faqs
8. **Post-write validation** – validate-template-content-blocks, compare-template-to-competitors, validate-template-internal-links, validate-template-content-completeness

**When publishing new template:** Run `php v2/scripts/blog/add-template-to-related-carousels.php --template=slug` to add template to matching blog post carousels.

See [TEMPLATE_CONTENT_CREATION_WORKFLOW.md](TEMPLATE_CONTENT_CREATION_WORKFLOW.md) for detailed content creation steps.

## Quick Start

```bash
# Full pipeline
php v2/scripts/templates/run-template-improvement-pipeline.php --template=dienstplan-excel-vorlage

# Phase by phase
php v2/scripts/templates/collect-template-keywords-sistrix.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/collect-template-paa-questions.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/collect-template-competitor-analysis.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/collect-template-faq-research-data.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/generate-template-serp-skeleton.php --template=dienstplan-excel-vorlage
# Manual: SERP_ANALYSIS.md (min 30 min), CONTENT_OUTLINE.md
php v2/scripts/templates/generate-template-content-outline.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/generate-template-section-briefs.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/generate-template-pre-content-checklist.php --template=dienstplan-excel-vorlage
# Keyword overlap: analyze-template-keyword-overlap.php --use-sistrix (before content for new templates)
# Phase gate: validate-template-improvement-readiness, validate-template-content-outline-quality, check-template-outline-block-overlap
php v2/scripts/templates/generate-template-content-blocks.php --template=dienstplan-excel-vorlage
```

## Data Directory Structure

```
docs/systems/templates/template-data/{template_id}/
├── data/
│   ├── keywords-sistrix.json
│   ├── paa-questions.json
│   ├── competitor-analysis.json
│   ├── competitive-depth-analysis.md
│   ├── section-briefs.md
│   ├── section-briefs.json
│   ├── performance-gsc.json
│   ├── faq-research.json
│   ├── faq-questions.json
│   └── faq-answers-optimized.json
├── content/
│   └── content.md
├── content-blocks.json
├── SERP_ANALYSIS.md
└── CONTENT_OUTLINE.md
```

## Content Blocks: Edit Files, Then Sync

Content blocks are edited in `content/content.md` (one file per template). Run sync to update `content-blocks.json`:

```bash
# Sync content.md → content-blocks.json
php v2/scripts/templates/sync-template-content-blocks.php --template=dienstplan-excel-vorlage
php v2/scripts/templates/sync-template-content-blocks.php --all

# Export: JSON → content files (migration)
php v2/scripts/templates/sync-template-content-blocks.php --all --export
```

See [TEMPLATE_CONTENT_EDIT_WORKFLOW.md](TEMPLATE_CONTENT_EDIT_WORKFLOW.md) and [TEMPLATE_CONTENT_BLOCKS_GUIDE.md](TEMPLATE_CONTENT_BLOCKS_GUIDE.md).

## Primary keyword vs. registry `name` (H1 and meta)

SISTRIX `primary_keyword` (in `template-data/{id}/data/keywords-sistrix.json` and `seo-meta.json`) can differ from the template registry `name` (e.g. slug stays `stundenzettel-excel-vorlage` while the head term is **stundenzettel vorlage**). In that case:

1. Set **`data/seo-meta.json`** title and description to lead with the SISTRIX primary phrase (keep slug canonical; do not invent URLs).
2. Add a **hero override** in [`v2/config/template-page-config.php`](../../v2/config/template-page-config.php) after `load_template_config` merges registry data (same pattern as `wochenplan-vorlage`): `hero.title`, `title_highlight` / `title_inline_highlight`, `subtitle`, optional `description`.
3. Optionally set registry **`meta_title`** for parity with other templates; `seo-meta.json` still wins for `<title>` when present.

This keeps the URL aligned with SISTRIX slug rules while matching high-volume query intent in H1 and SERP snippets.

## Hero Excel preview (`hero-visual.json`)

Before a template slug is listed in `$publishedTemplatesForIndex`, add `v2/data/template-hero-visuals/{slug}.json` with **eight** realistic data rows and correct column widths. The main hero **does not** pad or synthesize cells at runtime; published pages rely on this file only (see [TEMPLATE_HERO_VISUALS.md](TEMPLATE_HERO_VISUALS.md)).

```bash
php v2/scripts/templates/validate-hero-visuals.php
python3 v2/scripts/templates/audit-hero-visual-rows.py
```

## References

- [TEMPLATE_CANNIBALIZATION_GUIDE.md](TEMPLATE_CANNIBALIZATION_GUIDE.md)
- [TEMPLATE_CONTENT_CREATION_WORKFLOW.md](TEMPLATE_CONTENT_CREATION_WORKFLOW.md)
- [TEMPLATE_SKYSCRAPER_GUIDE.md](TEMPLATE_SKYSCRAPER_GUIDE.md)
- [TEMPLATE_AEO_GEO_CHECKLIST.md](TEMPLATE_AEO_GEO_CHECKLIST.md)
- [TEMPLATE_CONTENT_DEPTH_GUIDELINES.md](TEMPLATE_CONTENT_DEPTH_GUIDELINES.md)
- [TEMPLATE_FAQ_WORKFLOW.md](TEMPLATE_FAQ_WORKFLOW.md)
- [TEMPLATE_DATA_COLLECTION_GUIDE.md](TEMPLATE_DATA_COLLECTION_GUIDE.md)
- [TEMPLATE_SERP_ANALYSIS_WORKFLOW.md](TEMPLATE_SERP_ANALYSIS_WORKFLOW.md)