# Template Content Blocks Guide

**Last Updated:** 2026-02-15

Block types, frontmatter schema, sync workflow, and design tokens for template page content blocks.

## Overview

Content blocks are SEO sections rendered below the template hero. Each block has a type (section, card, callout, etc.) that determines visual styling. Content lives in `content/content.md` (one file per template); the sync script writes `content-blocks.json` for runtime.

## Block Types

| Type | Description | CSS Class |
|------|-------------|-----------|
| section | Standard H2 + prose | content-block-section |
| card | Highlighted box | content-block-card |
| card-blue | Blue card | content-block-card content-block-card-blue |
| card-green | Green card | content-block-card content-block-card-green |
| card-purple | Purple card | content-block-card content-block-card-purple |
| card-orange | Orange card | content-block-card content-block-card-orange |
| card-indigo | Indigo card | content-block-card content-block-card-indigo |
| callout | Important note | content-block-callout |
| examples | Numbered examples with left border | content-block-examples |
| table | Data table | content-block-table |
| steps | Step-by-step ordered list | content-block-steps |
| list | Bullet list with icons | content-block-list |

## When to Use Colored Containers

**Use `card-*` for:**
- Multi-card grids (e.g. ArbZG, Minijob, Branchen with `layout: grid-3`)
- Creative layouts with distinct sub-cards (grid-2, grid-3)
- Callouts (already separate block type)
- Highlighted tips when you want strong visual emphasis

**Use `section` for:**
- Standard H2 + prose blocks
- Tables (or `type: table` for table-only blocks)
- Steps, lists, plain text
- Blocks that only need an H2 + paragraphs

**Avoid:**
- Nesting tables inside card wrappers – use `type: section` or `type: table`
- Overusing `card-*` for simple prose – prefer `section` for cleaner look

**Styling alignment:** H3, tables, and links match blog/lexikon styling (Ordio blue table headers, visible links, consistent spacing).

## Frontmatter Schema

```yaml
---
heading: "Block heading (H2)"
type: section
keywords: ["primary", "secondary"]
order: 1
layout: ""   # optional: grid-2 for side-by-side cards
---
```

- **heading** (required): H2 text
- **type** (required): One of the block types above
- **keywords** (optional): Target keywords for SEO
- **order** (required): Display order (1-based)
- **layout** (optional): `grid-2` or `grid-3` for multi-column content
- **icon** (optional): `info`, `check`, `calculator`, `document` – for cards
- **subheading** (optional): H3 text within card (use with icon)

## Heading Hierarchy (H2/H3 Best Practices)

**Critical:** The component renders each block `heading` as **H2**. Content must not duplicate this.

### Rules

1. **Never duplicate block heading in content** – The component outputs H2 from frontmatter. Do not add `<h3>Block heading</h3>` at the start of content. Start with an intro paragraph or subsection.

2. **H2 = block heading (component)** – One H2 per block, from `heading:` in frontmatter.

3. **H3 = subsections within block** – Use H3 for distinct subtopics (e.g. "Deine Vorteile auf einen Blick", "Wie funktioniert das Audit?", "Warum eine DSGVO-Checkliste unverzichtbar ist"). Add H3s when a block has 3+ distinct subtopics or 4+ paragraphs.

4. **H4 = sub-subsections** – Use sparingly, only under H3. Cards with short labels can use H3 (not H4) to avoid skipping levels (H2 → H4 skips H3).

5. **Sequential hierarchy** – H2 → H3 → H4 (no skipping). Never H2 → H4.

6. **Vary subsection phrasing** – Avoid repetitive patterns ("Compliance-Checkliste" in every H3). Use question-style for PAA ("Wie funktioniert...?", "Warum...?") and declarative for structure ("Deine Vorteile", "Prüfpunkte im Überblick").

### Content Outline Planning

- Plan H2s (block headings) in CONTENT_OUTLINE.md – each block = one H2.
- Plan H3s per block when section has 3+ subtopics – add to section brief or content outline.
- Run `analyze-template-content-structure.py` to flag blocks that may need H3s (4+ paragraphs, 0 H3s).

## Content Format

- **Body:** HTML only (no Markdown parsing)
- **Allowed tags:** p, ul, ol, li, a, strong, em, div, span, table, thead, tbody, tr, th, td, h3, h4
- **Internal links:** Use canonical URLs (e.g. /schichtplan, /arbeitszeiterfassung)
- **Examples block:** Wrap items in `<div class="content-block-example-item">`
- **Callout:** Use `<div class="content-block-callout">` inside content
- **Steps:** Use `<ol>` for ordered lists; block type `steps` applies styling
- **Lists:** Use plain `<ol>` and `<ul>`—template-content-blocks.css provides Ordio blue markers and proper spacing. Avoid Tailwind list classes (list-inside, list-decimal) that can conflict.

## Sync Workflow

```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: content-blocks.json → content/*.md (migration)
php v2/scripts/templates/sync-template-content-blocks.php --all --export

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

## Design Tokens

Content block styles live in `v2/css/template-content-blocks.css` (shared with tools-pages). Colors:

- **Blue:** #eff6ff background, #bfdbfe border
- **Green:** #f0fdf4, #bbf7d0
- **Purple:** #faf5ff, #e9d5ff
- **Orange:** #fff7ed, #fed7aa
- **Indigo:** #eef2ff, #c7d2fe

## File Paths

- **Content (editable):** `docs/systems/templates/template-data/{id}/content/content.md`
- **Runtime JSON:** `docs/systems/templates/template-data/{id}/content-blocks.json`
- **Component:** `v2/components/template-content-blocks.php`
- **CSS:** `v2/css/template-content-blocks.css`

## Content-Driven Design

- **Design block types and layout per template** – avoid rigid 5-block pattern
- **Vary structure between templates:** dienstplan (ArbZG/Minijob angle) ≠ schichtplan (Schichtmodelle, 24h-Betrieb)
- **Answer-first:** 40–60 word direct answer below each H2
- **Word count:** Data-driven from competitive-depth-analysis.md. Skyscraper: outdo competitor average; aim for competitive range max.
- **AEO:** Answer-first (40–60 words), structured (steps, tables), comprehensive.
- **Reference:** [tools_einkommensteuer_rechner.php](../../v2/pages/tools_einkommensteuer_rechner.php) (lines 1284–1410) for rich card design: icons, H3s, grid layouts, callout with icon

## Checklist

- [ ] Icons in cards where appropriate
- [ ] Proper list/step spacing (content-block-list, content-block-steps)
- [ ] Grid layouts for multi-card sections (layout: grid-2, grid-3)
- [ ] Answer-first: first paragraph 40–60 words
- [ ] Block type variety (not all section/card)

## References

- [BLOCK_CONTENT_FORMAT.md](_templates/BLOCK_CONTENT_FORMAT.md) – Format specification
- [CONTENT_BLOCK_BRIEF.md](_templates/CONTENT_BLOCK_BRIEF.md) – Per-template content brief
- [KEYWORD_MAPPING.md](KEYWORD_MAPPING.md) – Keyword-to-section mapping
- [TEMPLATE_CONTENT_EDIT_WORKFLOW.md](TEMPLATE_CONTENT_EDIT_WORKFLOW.md) – Edit workflow