# Blog Table of Contents Best Practices Guide **Last Updated:** 2026-01-18 Comprehensive guide for creating optimal table of contents (TOC) structures for blog posts, including heading hierarchy, length recommendations, and UX best practices. ## Overview The blog TOC component automatically generates a table of contents from post headings. This guide covers best practices for heading structure, TOC length, and when to use different TOC modes. ## Heading Structure Guidelines ### Recommended Structure **H1:** Page title (one per page, handled by template) **H2:** Major sections/chapters (5-10 per post ideal) - Each H2 should represent a distinct topic or section - Use descriptive, keyword-rich headings - Examples: "Was sind Arbeitsstunden pro Monat?", "Wie berechnet man Arbeitsstunden pro Monat?" **H3:** Subsections under H2 (0–3 per H2 depending on need) - Use when H2 section has distinct subtopics, steps, or comparisons - H2 with paragraphs only is valid—don't force H3s for decoration - Examples: "Berechnung mit 4,35 Wochen", "Berechnung mit Arbeitstagen" **H4:** Sub-points under H3 (use sparingly) - Only when H3 section is very long or complex - Most posts don't need H4 headings ### Heading Hierarchy Rules 1. **Never skip levels:** H1 → H2 → H3 → H4 (don't go H2 → H4) 2. **One H1 per page:** H1 is the page title (handled by template) 3. **Logical nesting:** Each heading level should logically belong to its parent 4. **Consistent structure:** Maintain similar heading patterns across posts ### Ideal Heading Distribution | Post Length | H2 Count | H3 Count | Total TOC Items | Structure | |-------------|----------|----------|-----------------|-----------| | Short (<1,000 words) | 3-5 | 0-5 | 3-10 | Flat (H2 only or H2+H3) | | Medium (1,000-2,500 words) | 5-8 | 0-15 | 5-23 | Flat or Grouped | | Long (>2,500 words) | 8-12 | 5-30 | 13-42 | Grouped (H3s collapsed) | *H3 counts are ranges, not minimums. H2+paragraphs is valid for many sections.* ## TOC Length Recommendations ### UX Best Practices (Based on Research) **Ideal:** 5-7 primary items (Miller's Law: 7±2 cognitive limit) - Easy to scan and navigate - Low cognitive load - Fast decision-making **Acceptable:** 10-15 items - Still manageable for users - Flat structure works well - Good for medium-length content **Needs Optimization:** >15 items - Exceeds cognitive load for flat lists - Should use collapsible grouping - H3s grouped under H2s, collapsed by default **Too Long:** >30 items - Consider content restructuring - Split into multiple posts - Or use H2-only TOC mode ### Current Implementation The TOC component automatically applies grouping when: - Total TOC items >15 (H2 + H3 count) - H3s are grouped under parent H2s - H3 groups are collapsed by default - "Expand all" / "Collapse all" toggle available **Example:** - Post with 12 H2 + 26 H3 = 38 items → **Grouped mode** - Post with 5 H2 + 8 H3 = 13 items → **Flat mode** ## When to Use Different TOC Modes ### Flat Structure (Default for ≤15 items) **Use when:** - TOC has ≤15 total items - Content is relatively short (<2,500 words) - All sections are equally important - Users need to see all sections at once **Benefits:** - Simple, clean interface - All navigation visible immediately - Faster scanning - Less interaction required ### Grouped Structure (Auto-applied for >15 items) **Use when:** - TOC has >15 total items - Content is long (>2,500 words) - H2 sections have multiple H3 subsections - Reducing initial cognitive load is important **Benefits:** - Reduced initial visual clutter - Better organization - Easier to find major sections (H2s) - Maintains full navigation (H3s available on expand) **Behavior:** - H2 sections always visible - H3 sections collapsed by default - Click H2 or chevron to expand/collapse - "Expand all" / "Collapse all" toggle - Auto-expands parent H2 when scrolling to H3 ### H2-Only Mode (Manual override) **Use when:** - TOC has >30 items even with grouping - H3s are not critical for navigation - Content structure is very flat (many H2s, few H3s) - Simpler navigation preferred **Configuration:** ```php $toc_items = build_toc_structure($headings_data, [ 'max_depth' => 2 // H2 only ]); ``` ## Content Structure Best Practices ### For Content Creators **Planning Your Post Structure:** 1. **Outline major topics first** (H2s) - Aim for 5-10 major sections - Each H2 should be a distinct topic - Use question format for SEO: "Was ist...?", "Wie berechnet man...?" 2. **Add subsections only when needed** (H3s) - Use H3s to break down complex H2 sections - Aim for 2-3 H3s per H2 (not more than 5) - Each H3 should add specific detail to H2 topic - When H3s are used: Optional intro paragraph between H2 and first H3 for smoother flow. Content-driven. 3. **Avoid excessive H3s** - If H2 has >5 H3s, consider splitting H2 into multiple H2s - Or restructure content to reduce nesting depth - Too many H3s create long, overwhelming TOC 4. **Monitor TOC length** - Check TOC length during content creation - If approaching 15+ items, consider restructuring - Use analysis script: `python3 v2/scripts/blog/analyze-toc-structure.py` ### Restructuring vs Grouping **When to Restructure Content:** - TOC has >30 items even with grouping - Many H2s with only 1-2 H3s each (flatten structure) - H2s are too granular (combine related H2s) - Content feels disorganized **When Grouping is Sufficient:** - TOC has 16-30 items - Clear H2/H3 hierarchy exists - Content structure is logical - Grouping improves UX without content changes ## Accessibility Requirements ### ARIA Attributes **Required for Collapsible TOC:** - `aria-expanded` - State of expand/collapse (true/false) - `aria-controls` - ID of controlled element (H3 container) - `aria-label` - Descriptive label for expand/collapse button - `role="button"` - For expand/collapse buttons **Example:** ```html