# Template Block Content Format

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

## Overview

All blocks for a template live in `template-data/{id}/content/content.md` (one file per page). Blocks are separated by `--- block-N ---`; each has YAML frontmatter + HTML body. The sync script reads content.md and writes `content-blocks.json`.

## File Structure

```
template-data/{template_id}/content/
└── content.md    # All blocks in one file
```

## Format

Blocks are separated by `--- block-N ---`. Each block:

```yaml
--- block-1 ---
---
heading: "Block heading (H2)"
type: section
keywords: ["primary", "secondary"]
order: 1
---

<p>HTML content here. Use standard HTML: p, ul, ol, a, strong, em, div, table, etc.</p>

--- block-2 ---
---
heading: "Next block"
type: steps
...
---
<ol>...</ol>
```

## Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| heading | Yes | H2 heading text |
| type | Yes | section, card, card-blue, card-green, card-purple, card-orange, card-indigo, callout, examples, table, steps, list |
| keywords | No | Array of target keywords |
| order | Yes | Display order (1-based) |
| layout | No | `grid-2` or `grid-3` for multi-column content |
| icon | No | Card icon: `info`, `check`, `calculator`, `document` |
| subheading | No | H3 subheading within card (use with icon) |

## Block Types

- **section** – Standard H2 + prose
- **card** – Highlighted box (content-block-card)
- **card-blue**, **card-green**, **card-purple**, **card-orange**, **card-indigo** – Colored cards
- **callout** – Important note (content-block-callout); gets info icon automatically
- **examples** – Wrapper for content-block-examples; children use content-block-example-item
- **table** – content-block-table; use for comparisons (e.g. Schichtmodelle, Vorlage vs. Software)
- **steps** – Ordered list with step styling; feeds HowTo schema
- **list** – Bullet list with optional icons

**When to use table vs. examples:** Use `type: table` for structured comparisons (Modell | Zeiten | Typisch für). Use `type: examples` for narrative examples with content-block-example-item divs.

## 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 a 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` so the table is not inside a colored container
- Overusing `card-*` for simple prose – prefer `section` for cleaner look

## Body

- Use HTML only (no Markdown parsing)
- Allowed tags: p, ul, ol, li, a, strong, em, div, span, table, thead, tbody, tr, th, td, h3, h4
- **Lists:** Use plain `<ol>` and `<ul>`—CSS provides Ordio blue markers, proper indentation, and spacing. Avoid Tailwind list classes (list-inside, list-decimal) that can conflict with prose styling.
- Internal links: use canonical URLs (e.g. /schichtplan, /arbeitszeiterfassung)
- **Paragraph length:** 40–80 words preferred; flag if > 100
- **H3 subheadings:** Use when block has 4+ paragraphs or 6+ list items; group long lists with H3s
- **Front-load:** Headings and first sentences should convey key takeaway
- **Internal links:** Contextual anchor text only. Integrate links where the topic is naturally discussed. Do not add repetitive CTAs (e.g. "Weitere Vorlagen: Vorlagen") at the end of every block.