# Content Flow Guidelines

**Last Updated:** 2026-03-24

## Overview

This document defines content flow requirements for blog posts to ensure logical progression, optimal user experience, and SEO/AEO/GEO optimization.

## Reader-facing copy (no research leakage)

Outline evidence, PAA ids, SISTRIX notes, and SERP commentary belong in **outline and data files**, not in HTML bodies or reader FAQs. Do not paste internal methodology labels (e.g. „Suchanfragen“, „PAA“, tool names) into article prose; answer the reader in natural German instead. See [READER_FACING_COPY_GUARDRAILS.md](READER_FACING_COPY_GUARDRAILS.md) and `php v2/scripts/blog/validate-reader-facing-copy.php`.

## Core Principles

### 1. Introduction (Never Start with "Definition:")

**Rule:** Never start a post or intro paragraph with "Definition:" or "**Definition:** [term]".

**Rationale:** Dictionary-style openings feel encyclopedic and AI-generated. Users expect engaging, human-first intros that introduce the topic in an interesting way – a hook (bold claim, surprising stat, question, relatable scenario), context, and value proposition. The definition belongs in the first H2 section; the intro should not repeat it verbatim. The first H2 should expand or deepen the intro, not echo it.

**Good intro patterns:** Hook → Context → Value proposition. Primary keyword in first paragraph. 2–3 paragraphs max. See [CONTENT_OUTLINE template](posts/_templates/CONTENT_OUTLINE.md) Introduction section and [AI_CONTENT_AVOIDANCE_GUIDE.md](../AI_CONTENT_AVOIDANCE_GUIDE.md).

**Body HTML (`content-draft.html` / published `content.text`):** The first block after the `#ordioTextContent` wrapper must be **intro `<p>` paragraphs** (optionally followed by a `blog-note`), not the first section `<h2>`. Skipping the intro reads like a template glitch and skips the hook the guidelines above require.

**FAQ questions:** Phrase questions the way readers search — **no mechanical title prefix** (e.g. `40-Stunden-Woche: …`). If `validate-faq-topic-relevance.php` complains, enrich the wording with clear on-topic terms (e.g. „40 Stunden“, „Wochenarbeitszeit“) instead of prefixing the post title.

### 2. Definition Placement

**Rule:** Core definitions must appear early in content (within first 20% of text).

**Rationale:** Readers need to understand key concepts before encountering examples, discussions, or advanced topics.

**Exceptions:**
- **Multi-section posts:** Definitions can appear early within their respective sections (e.g., section 2 of 3)
- **Sub-topic definitions:** Secondary definitions can appear later if the main definition is early

**Patterns to detect:**
- `Definition: [term]`
- `Was ist [term]?`
- `Was sind [term]?`
- `Was bedeutet [term]?`
- `Was ist ein/eine/der/die/das [term]?`

### 3. Logical Flow Structure

**Ideal structure:**
1. **Introduction** - Hook, context, what the post covers
2. **Core Definition** - What is the main topic? (within first 20%)
3. **Explanation** - How it works, why it matters
4. **Examples** - Practical examples, use cases
5. **Advanced Topics** - Complex scenarios, edge cases
6. **Conclusion** - Summary, next steps

**Content progression:**
- Simple → Complex
- General → Specific
- Theory → Practice
- Problem → Solution

### 4. FAQ Separation

**CRITICAL:** FAQs must NEVER appear in `content.html`. They belong ONLY in the `faqs` array.

**Why:**
- FAQs are rendered separately via `BlogFAQ.php` component
- Duplicate content hurts SEO
- Separates structured data from main content

**What to remove from content:**
- FAQ headings (`<h2>FAQ</h2>`, `<h3>Häufige Fragen</h3>`)
- FAQ wrapper divs (`<div class="schema-faq">`)
- Individual FAQ sections in content HTML

**Where FAQs belong:**
- `faqs` array in post JSON file
- Rendered via `BlogFAQ.php` component
- Schema markup generated automatically

### 5. Heading Structure (SEO & UX)

**Rule:** One H1 per page (in PostHeader); content uses H2 → H3 only.

**Best practices:**
- **H2:** 8–12 main sections; prefer question-style for PAA ("Was ist X?", "Welche Arten...?")
- **H3:** Sub-sections when 3+ distinct subtopics; otherwise use lists
- **TOC:** Auto-generated from H2/H3; enables jump links and improves scannability

**See:** [BLOG_HEADING_BEST_PRACTICES.md](BLOG_HEADING_BEST_PRACTICES.md) for full guidelines.

### 6. Non-Text Element Preservation

**Preserve these elements:**
- Calculators (Alpine.js `x-data` components)
- Embeds (iframes, videos)
- Images
- Tables
- Scripts (with `data-preserved="true"`)

**You can:**
- Move elements to better positions
- Update surrounding text
- Optimize alt text and captions

**You cannot:**
- Remove functional elements
- Break calculator functionality
- Remove required scripts

## Content Flow Checklist

### Before Publishing

- [ ] Core definition appears within first 20% of content
- [ ] Logical flow: Intro → Definition → Explanation → Examples → Advanced
- [ ] No FAQ sections in `content.html`
- [ ] FAQs exist only in `faqs` array
- [ ] Non-text elements preserved and functional
- [ ] Primary keyword in first paragraph
- [ ] Proper heading hierarchy (H2 → H3); no H1 in content; 8–12 H2s
- [ ] Smooth transitions between sections
- [ ] Content optimized for SEO/AEO/GEO
- [ ] User-friendly and valuable content

### Definition Placement

- [ ] Main definition appears early (within first 20%)
- [ ] Definition is clear and comprehensive
- [ ] Definition uses natural language
- [ ] Definition includes primary keyword naturally
- [ ] Sub-topic definitions appear logically within their sections

### FAQ Management

- [ ] No FAQ headings in `content.html`
- [ ] No FAQ wrapper divs in `content.html`
- [ ] FAQs exist only in `faqs` array
- [ ] FAQ set is optimal (10-15 questions)
- [ ] FAQs complement content (don't duplicate)
- [ ] FAQ answers are 40-80 words
- [ ] FAQs include primary keyword naturally

## Common Issues & Solutions

### Issue: Definition Appears Too Late

**Problem:** Definition appears after 30%+ of content, after examples/discussions.

**Solution:**
1. Identify the definition section
2. Extract it from current position
3. Move it to appear right after intro paragraph
4. Ensure smooth transition

**Example:**
```html
<!-- BEFORE (WRONG) -->
<p>Intro paragraph...</p>
<h2>Examples</h2>
<p>Example content...</p>
<h3>Was ist Arbeitszeit?</h3>
<p>Definition...</p>

<!-- AFTER (CORRECT) -->
<p>Intro paragraph...</p>
<h3>Was ist Arbeitszeit?</h3>
<p>Definition...</p>
<h2>Examples</h2>
<p>Example content...</p>
```

### Issue: FAQs in Content HTML

**Problem:** FAQ sections found in `content.html` instead of `faqs` array.

**Solution:**
1. Extract FAQs from content HTML
2. Add to `faqs` array in JSON
3. Remove FAQ sections from `content.html`
4. Verify FAQs render correctly via component

### Issue: Illogical Content Order

**Problem:** Content discusses topics before defining them.

**Solution:**
1. Map all content sections
2. Identify dependencies
3. Reorder: definitions first, then explanations, then examples
4. Update internal links if sections move

## Multi-Section Posts

For posts with numbered sections (e.g., "1. Topic A", "2. Topic B"):

**Acceptable pattern:**
- Each section can have its own definition
- Definitions appear early within their sections
- Overall position may be >30% but is acceptable if within section

**Example:**
```
Intro
1. Mindestlohnerhöhung
   → Definition appears early in section 1
2. E-Rechnungspflicht
   → Definition appears early in section 2 (may be >30% overall)
3. Mehrwegpflicht
   → Definition appears early in section 3 (may be >30% overall)
```

## Validation

Use `v2/scripts/blog/analyze-content-flow.php` to check:
- Definition placement
- FAQ sections in content
- Heading hierarchy
- Content flow score

**Target scores:**
- Flow score: ≥80/100
- Definitions: All early (≤20%) or early within sections
- FAQs: None in content HTML

## Related Documentation

- [BLOG_HEADING_BEST_PRACTICES.md](BLOG_HEADING_BEST_PRACTICES.md) – Heading structure, TOC, SEO
- `.cursor/rules/blog-content-flow.mdc` - Cursor rules for content flow
- `v2/scripts/blog/validate-content-flow.php` - Pre-commit validation
- `docs/content/CONTENT_CREATION_WORKFLOW_2026.md` - Content creation workflow