# Content Structure & Formatting Guide

**Last Updated:** 2026-03-18  
**Purpose:** Comprehensive guide to content structure, formatting, and visual hierarchy for all content types

## Overview

This guide provides detailed guidelines for structuring and formatting content to maximize readability, SEO performance, and user experience across all content types (blog posts, product pages, tools pages, templates).

## Header Hierarchy

### Critical Rules

1. **H1: Page/Post Title Only**

   - One H1 per page
   - Displayed in header component (not in content)
   - Content should never contain H1 tags

2. **H2: Main Sections**

   - First heading in content must be H2
   - 5-10 for most posts; 8-12 for main topics (see [blog/CONTENT_DEPTH_GUIDELINES.md](blog/CONTENT_DEPTH_GUIDELINES.md))
   - Main content divisions

3. **H3: Subsections**

   - Under H2 sections
   - Used for detailed breakdowns
   - Can repeat at same level
   - **H3 optional:** Use case-by-case when sections have distinct subtopics, steps, or comparisons. H2+paragraphs valid. When H3s used: optional intro between H2 and first H3 for smoother flow. See [blog/CONTENT_WRITING_GUIDELINES.md](blog/CONTENT_WRITING_GUIDELINES.md) and [blog/HEADING_HIERARCHY_GUIDE.md](blog/HEADING_HIERARCHY_GUIDE.md).

4. **H4: Sub-subsections**

   - Under H3 sections
   - Use sparingly
   - Only when deeper hierarchy needed

5. **H5-H6: Avoid**
   - Avoid if possible
   - Use only if absolutely necessary

### Sequential Hierarchy Rules

**Required:**

- H2 → H3 → H4 (sequential, no skipping)
- Can repeat same level (H2 → H2 → H3)

**Never:**

- H2 → H4 (skipped H3)
- H3 → H2 (backwards hierarchy)
- H4 → H2 (backwards hierarchy)

### Common Patterns

**List-Based Posts** (e.g., "5 Tips for..."):

```
H2: Tip 1: Title
H2: Tip 2: Title
H2: Tip 3: Title
```

**Guide Posts** (e.g., "How to..."):

```
H2: Introduction
H2: Step 1: Title
  H3: Details
H2: Step 2: Title
  H3: Details
```

**FAQ Posts:**

```
H2: Question 1
H2: Question 2
H2: FAQ (if FAQ section exists)
```

**Standard Blog Post:**

```
H2: Main Section 1
  H3: Subsection 1.1
  H3: Subsection 1.2
H2: Main Section 2
  H3: Subsection 2.1
    H4: Sub-subsection 2.1.1 (if needed)
```

### SEO Best Practices

- **Keyword Optimization:** Include primary keyword in H2 headings naturally
- **Descriptive Headings:** Clear, descriptive headings that indicate content
- **Logical Flow:** Headings should create logical content flow
- **Semantic Meaning:** Headings reflect actual content structure

## Paragraph Structure

### Length Guidelines

**Optimal:** 2-3 sentences per paragraph
**Maximum:** 4 sentences per paragraph
**Minimum:** 1 sentence (for emphasis)

### Structure Guidelines

- **One Main Idea:** Each paragraph should focus on one main idea
- **Topic Sentence:** Start with clear topic sentence
- **Supporting Sentences:** Follow with supporting details
- **White Space:** Use white space effectively to break up text

### Examples

**Good (2-3 sentences):**
"Zeiterfassung ist gesetzlich vorgeschrieben – das bedeutet: Du musst die Arbeitszeiten deiner Mitarbeiter dokumentieren. Digitale Lösungen machen das einfacher: Sie erfassen die Zeiten automatisch und übertragen sie direkt in die Lohnabrechnung."

**Bad (Too Long):**
"Zeiterfassung ist gesetzlich vorgeschrieben – das bedeutet: Du musst die Arbeitszeiten deiner Mitarbeiter dokumentieren. Digitale Lösungen machen das einfacher: Sie erfassen die Zeiten automatisch und übertragen sie direkt in die Lohnabrechnung. Das spart Zeit und verhindert Fehler. Außerdem kannst du die Daten jederzeit abrufen und auswerten. Viele Betriebe nutzen bereits digitale Zeiterfassungssysteme und sind damit sehr zufrieden."

## Lists

### When to Use Lists

**Use Lists When:**

- Presenting multiple related items
- Breaking down steps or processes
- Highlighting key points
- Making content scannable
- Comparing items

**Don't Use Lists When:**

- Content flows better as paragraphs
- Only one or two items
- Items need detailed explanation

### Bulleted Lists (Unordered)

**Use For:**

- Related items without order
- Features or benefits
- Key points
- Examples

**Format:**

```markdown
- Item 1
- Item 2
- Item 3
```

**Example:**
"Digitale Zeiterfassung bringt dir mehrere Vorteile:

- Sie ist genauer als manuelle Erfassung
- Sie spart Zeit bei der Lohnabrechnung
- Sie hilft dir dabei, gesetzeskonform zu arbeiten"

### Numbered Lists (Ordered)

**Use For:**

- Step-by-step instructions
- Sequential processes
- Ranked items
- Procedures

**Format:**

```markdown
1. Step 1
2. Step 2
3. Step 3
```

**Example:**
"So richtest du digitale Zeiterfassung ein:

1. Wähle ein Zeiterfassungssystem aus
2. Richte die Systemeinstellungen ein
3. Schulde deine Mitarbeiter ein
4. Starte die Zeiterfassung"

### List Best Practices

- **Consistent Formatting:** Use same list type throughout
- **Parallel Structure:** Keep items grammatically parallel
- **Appropriate Length:** 3-7 items per list (optimal)
- **Clear Items:** Each item should be clear and complete
- **Punctuation:** Use periods for complete sentences, none for fragments

### Term-Definition Patterns (Multiple Terms in One Block)

**Avoid:** Cramming multiple `**[term]**: [definition]**` pairs into a single paragraph. This reduces scannability and feels dense.

**❌ Bad (multiple terms in one paragraph):**
```
Für Kleinbetriebe: App-Lösungen. Für mittlere Betriebe: Terminal + App. Für Schichtbetrieb: Schichtplanung.
App-basierte Zeiterfassung: Mobile Erfassung. Browser-basierte Zeiterfassung: Webbasiert. Excel: Manuelle Erfassung.
```

**✅ Good – use a bullet list:**
```html
<ul>
<li><strong>Für Kleinbetriebe</strong>: App- oder Browser-Lösungen – geringer Aufwand, keine Hardware.</li>
<li><strong>Für mittlere Betriebe</strong>: Kombination aus Terminal und App für flexible Arbeitsorte.</li>
<li><strong>Für Schichtbetrieb</strong>: Integration mit Schichtplanung.</li>
</ul>
```

**✅ Good – use separate paragraphs** (when each term needs 2+ sentences):
```html
<p><strong>Stempeluhr</strong>: Klassische Stechuhr – stempelt Zeiten auf Karte oder speichert digital. Noch weit verbreitet.</p>
<p><strong>Zutrittskontrolle</strong>: Erfasst automatisch beim Betreten und Verlassen – oft kombiniert mit Zeiterfassung.</p>
```

**✅ Good – use a table** (when comparing 3+ terms with similar structure):
Use `<table>` for side-by-side comparisons (e.g. Begriff | Bedeutung).

**Decision rule:** If you have 2+ term-definition pairs in one paragraph, refactor to a list, separate paragraphs, or a table.

## Quotes and Blockquotes

### When to Use Quotes

**Use Quotes For:**

- Customer testimonials
- Expert opinions
- Important statements
- Emphasis
- External citations

**Don't Use Quotes For:**

- Regular content
- Lists
- Code examples

### Format

**HTML:**

```html
<blockquote>
  <p>Quote text here.</p>
  <cite>— Source Name</cite>
</blockquote>
```

**Markdown:**

```markdown
> Quote text here.
> — Source Name
```

### Examples

**Customer Testimonial:**

> "Mit Ordio sparen wir etwa 5 Stunden pro Woche bei der Lohnabrechnung. Das ist ein enormer Zeitgewinn für uns."
> — Max Mustermann, Restaurantbesitzer

**Expert Opinion:**

> "Digitale Zeiterfassung ist nicht nur gesetzlich vorgeschrieben, sondern auch ein wichtiger Schritt zur Digitalisierung des Betriebs."
> — Dr. Beispiel, Arbeitsrechtsexperte

## Visual Hierarchy

### Principles

1. **Size:** Larger elements draw more attention
2. **Contrast:** High contrast elements stand out
3. **Spacing:** White space creates separation
4. **Position:** Top-left area gets most attention
5. **Color:** Use color strategically for emphasis

### Implementation

**Headings:**

- H2: Largest content heading
- H3: Medium-sized subheading
- H4: Smaller sub-subheading

**Text:**

- Body text: Standard size (16px)
- Emphasis: Bold or italic
- Links: Underlined or colored

**Spacing:**

- Between sections: Generous spacing
- Between paragraphs: Moderate spacing
- Between list items: Consistent spacing

## Content Sections

### Standard Structure

**1. Introduction (100-200 words)**

- Context and background
- Value proposition
- What readers will learn
- Hook to keep reading

**2. Main Content (800-1,500 words)**

- Detailed explanations
- Examples and use cases
- Best practices
- Step-by-step guides
- Multiple H2 sections

**3. FAQ Section (200-400 words)**

- 5-10 common questions
- Comprehensive answers (40-60 words each)
- Related topics
- H2: "Häufig gestellte Fragen (FAQ)"

**4. Conclusion (50-100 words)**

- Key takeaways
- Next steps
- Related resources
- Call-to-action

### Content Type Variations

**Blog Posts:**

- Introduction → Main Content → FAQ → Conclusion
- 1,200+ words (informational), 300-800 words (news)

**Product Pages:**

- Hero → Benefits → Features → Use Cases → CTA
- 500-1,000 words

**Tools Pages:**

- Introduction → How It Works → Examples → FAQ
- 800-1,500 words

**Template Pages:**

- Introduction → Features → Download → Usage Guide
- 500-1,000 words
- **Heading hierarchy:** Block heading = H2 (rendered by component). Content: no duplicate H3 of block heading; use H3 for subsections; H2 → H3 → H4 (no skipping). See [TEMPLATE_CONTENT_BLOCKS_GUIDE.md](../systems/templates/TEMPLATE_CONTENT_BLOCKS_GUIDE.md#heading-hierarchy-h2h3-best-practices).

## Readability Best Practices

### Sentence Length

**Optimal:** Mix short (5-10 words) and longer (15-25 words) sentences
**Maximum:** 30 words per sentence
**Minimum:** 5 words per sentence

**Example:**
"Zeiterfassung ist gesetzlich vorgeschrieben. Das bedeutet: Du musst die Arbeitszeiten deiner Mitarbeiter dokumentieren. Aber digitale Lösungen machen das einfacher – und helfen dir dabei, Fehler zu vermeiden und Zeit zu sparen."

### Word Choice

- **Simple Words:** Use simple, clear words
- **Active Voice:** Prefer active voice over passive
- **Concrete Terms:** Use specific, concrete terms
- **Avoid Jargon:** Explain technical terms when necessary

### Formatting for Readability

- **Short Paragraphs:** 2-3 sentences max
- **Headings:** Break up content with headings
- **Lists:** Use lists for scannable content
- **White Space:** Generous white space
- **Images:** Include relevant images

## Content Formatting Standards

### Text Formatting

**Bold:**

- Use for emphasis
- Key terms
- Important points
- Don't overuse

**Italic:**

- Use for emphasis
- Foreign terms
- Titles
- Don't overuse

**Underline:**

- Use only for links
- Don't use for emphasis

### Link Formatting

**Anchor Text:**

- Descriptive and natural
- No leading or trailing whitespace
- Includes relevant keywords
- Contextually appropriate

**Example:**
✅ `<a href="/schichtplan">Schichtplanung</a>`
❌ `<a href="/schichtplan"> Schichtplanung </a>`

### Image Formatting

**Alt Text:**

- Descriptive and specific
- Includes relevant keywords
- Describes image content
- Not just "image" or "photo"

**Format:**

- WebP format preferred
- Responsive images (srcset)
- Proper dimensions
- Optimized file sizes

## Examples by Content Type

### Blog Post Example

```markdown
# Post Title (H1 - in header)

[Introduction paragraph - 100-200 words]

## Was ist digitale Zeiterfassung? (H2)

[Content paragraph]

### Gesetzliche Anforderungen (H3)

[Content paragraph]

### Vorteile digitaler Zeiterfassung (H3)

[Content paragraph]

- Vorteil 1
- Vorteil 2
- Vorteil 3

## Wie funktioniert digitale Zeiterfassung? (H2)

[Content paragraph]

### Schritt 1: System auswählen (H3)

[Content paragraph]

### Schritt 2: Einrichtung (H3)

[Content paragraph]

## Häufig gestellte Fragen (FAQ) (H2)

[FAQ content]

## Fazit (H2)

[Conclusion paragraph]
```

### Product Page Example

```markdown
# Product Name (H1 - in header)

[Hero section]

## Vorteile (H2)

- Vorteil 1
- Vorteil 2
- Vorteil 3

## Funktionen (H2)

[Content paragraph]

### Funktion 1 (H3)

[Content paragraph]

### Funktion 2 (H3)

[Content paragraph]

## Use Cases (H2)

[Content paragraph]

[CTA section]
```

## Accessibility Considerations

### Heading Structure

- **Screen Readers:** Use proper heading hierarchy for navigation
- **Document Outline:** Headings create document outline
- **Keyboard Navigation:** Proper structure enables efficient navigation

### Content Formatting

- **Alt Text:** All images need descriptive alt text
- **Link Text:** Descriptive link text (not "click here")
- **Color Contrast:** Ensure sufficient color contrast
- **Text Size:** Use readable font sizes (minimum 16px)

## SEO Considerations

### Header Optimization

- **Keyword Placement:** Include primary keyword in H2 headings
- **Descriptive Headings:** Clear, descriptive headings
- **Logical Structure:** Proper hierarchy helps SEO

### Content Structure

- **Scannable Content:** Headings, lists, short paragraphs
- **Internal Linking:** Link to related content
- **Schema Markup:** Use appropriate schema markup

## Validation Checklist

### Structure Checklist

- [ ] H1 is page/post title only (in header)
- [ ] First content heading is H2
- [ ] Sequential hierarchy (no skipping levels)
- [ ] No backwards hierarchy
- [ ] Logical content flow

### Formatting Checklist

- [ ] Short paragraphs (2-3 sentences max)
- [ ] No multiple term-definition pairs in one paragraph (use list or separate paragraphs)
- [ ] Lists used appropriately
- [ ] Quotes used for emphasis/testimonials
- [ ] Proper white space
- [ ] Images have alt text
- [ ] Links have descriptive anchor text

### Readability Checklist

- [ ] Varied sentence lengths
- [ ] Simple, clear language
- [ ] Active voice preferred
- [ ] Technical terms explained
- [ ] Content is scannable

## Related Documentation

- `docs/content/blog/HEADING_HIERARCHY_GUIDE.md` - Detailed heading hierarchy guide
- `docs/content/CONTENT_WRITING_BEST_PRACTICES_2026.md` - Content writing best practices
- `docs/content/blog/CONTENT_QUALITY_STANDARDS_2026.md` - Content quality standards

## References

- WCAG 2.1 Accessibility Guidelines
- SEO best practices for content structure
- UX best practices for readability
- Content formatting standards