# Template System Overview

**Last Updated:** 2026-03-26

Single entry point for the template system. **`template-registry.json`** is the source of truth for generator metadata and publish status; **`v2/config/templates-index-config.php`** controls which published templates appear on `/vorlagen` and in carousels.

## Production templates

**Count:** All entries with `status: "published"` in `v2/systems/excel-template-generator/data/template-registry.json` are production-ready in the generator (currently **20**). Not every published slug may have a public URL until `.htaccess`, sitemap, and llms files are aligned—verify routes before assuming a page is live.

**Detail pages:** Canonical URLs are `https://www.ordio.com/vorlagen/{slug}`. A full list of documented pages is in [TEMPLATES_PAGES_INVENTORY.md](../../content/pages/templates-pages/TEMPLATES_PAGES_INVENTORY.md).

**Recent addition:** `bewerbung-vorlage` — Bewerbungsmappe (Deckblatt, Anschreiben, Lebenslauf) in Excel/Google Sheets.

## Source of Truth

- **Registry:** `v2/systems/excel-template-generator/data/template-registry.json`
  - `status: "published"` = included in production generator/registry
  - `status: "draft"` = not ready for public routes
  - `status: "deprecated"` = redirects to canonical (e.g. payroll-basic → lohnabrechnung-vorlage)
- **Index & carousels:** `v2/config/templates-index-config.php` — `$publishedTemplatesForIndex`, `$templateSlugToFilterKey`, `$templateIndexCardOverrides`

## Routes

- **Apache:** `.htaccess` `RewriteRule` entries under `# Templates` map `/vorlagen/{slug}` → `templates_template.php?template_id=…`
- **Note:** `.htaccess` may contain **duplicated** template blocks; when adding a rule, insert the same rule in each duplicate block or consolidate blocks (see [TEMPLATE_PUBLICATION_CHECKLIST.md](TEMPLATE_PUBLICATION_CHECKLIST.md)).
- **Draft templates:** No route → direct URLs return 404
- **Canonicalization:** dienstplan, dienstplan-excel → dienstplan-excel-vorlage; schichtplan, schichtplan-excel → schichtplan-excel-vorlage
- **Deprecated redirects:** Old English slugs (shift-planning-basic, payroll-basic, etc.) 301 to canonical German URLs

## Publish Workflow

When promoting a draft template to production:

1. Run improvement pipeline (content blocks, FAQs, validation)
2. Set `status: "published"` in template-registry.json
3. Add slug to `$publishedTemplatesForIndex` in templates-index-config.php
4. Add index card override in `$templateIndexCardOverrides` if needed
5. Add `.htaccess` rule(s) for `/vorlagen/{slug}` (verify all duplicate `# Templates` sections if present)
6. Add URL to `v2/data/sitemap-pages.json`, `html/llms.txt`, `html/llms-full.txt`; run `python3 v2/scripts/llms/validate-llms-metadata.py --report`
7. Optional: `php v2/systems/excel-template-generator/scripts/generate-template-routes.php` (verify section boundaries if duplicates exist)
8. OG: `v2/scripts/og-images/og-image-specs.json` + generate `v2/img/og/{slug}.webp`; optional `v2/config/og-image-registry.php`
9. HubSpot: `pageNameMap` in `v2/api/submit-template.php` for `vorlagen/{slug}`

## Deprecate Workflow

When merging or retiring a template:

1. Set `status: "deprecated"` in template-registry.json
2. Add `deprecated_redirect: "canonical-slug"`
3. Add 301 redirect in .htaccess (or run route generator — deprecated redirects are hardcoded)
4. templates_template.php will 301 deprecated templates automatically

## Decision Tree

- **New template:** Run full improvement pipeline; slug = German keyword-based per TEMPLATE_SLUG_MIGRATION_GUIDE.md
- **Improve existing:** Run content/FAQ improvement phases only
- **Deprecate:** Set deprecated + redirect; remove from index config

## Key Files

| Purpose | File |
|---------|------|
| Status source of truth | template-registry.json |
| Index display | templates-index-config.php |
| Routes | .htaccess |
| Route generator | generate-template-routes.php |
| Page inventory | docs/content/pages/templates-pages/TEMPLATES_PAGES_INVENTORY.md |