Modern documentation and blog themes face a fundamental tension: how do you help readers navigate long articles without sacrificing content space or creating jarring layout shifts? This post compares different Table of Contents (TOC) patterns and explains the design trade-offs behind each.

The Navigation Problem

Technical blogs and documentation often contain deeply structured content with multiple heading levels. Readers need to:

1. Understand document structure at a glance
2. Jump to specific sections quickly
3. Track reading progress through the article
4. Maintain spatial orientation while interacting with navigation

These requirements often conflict with each other.

Option 1: No TOC

The minimalist approach: let the content speak for itself.

When It Works

• Short articles (< 5 headings)
• Linear narratives that shouldn’t be skipped
• Mobile-first content where screen space is precious
• Posts where in-content anchor links suffice

When It Fails

• Long technical documentation
• Reference material users need to jump around
• Multi-section tutorials
• Any content where users need to maintain context across sections

Design Philosophy

“Reading should be distraction-free. If your article needs complex navigation, it’s probably too long.”

This works for Medium-style blogs but fails for technical documentation where comprehensive coverage requires length.

Option 2: Text-Based TOC

The traditional approach: a sidebar list of clickable headings.

Sub-Variants

Always-Visible Sidebar

Pros:

• Immediate visibility
• Full heading text readable
• Standard pattern users recognize

Cons:

• Consumes 200-300px horizontal space
• Wasted on short articles
• Requires responsive collapse on mobile

Auto-Follow Highlighting

Pros:

• Shows current position
• Provides reading progress feedback
• Familiar pattern from documentation sites

Cons:

• Can be distracting if highlight changes too frequently
• Requires scroll tracking implementation
• May compete with content for attention

Auto-Collapsing Branches

Pros:

• Scales well with deep heading hierarchies (H2 → H3 → H4)
• Keeps TOC from becoming overwhelming

Cons:

• Layout shift problem: “I was about to click item 5 and it collapsed”
• Unpredictable UI movement frustrates users
• Manual collapse is fine; automatic collapse is usually a mistake

Design Philosophy

“Navigation should always be visible and predictable.”

This is the MDN/Stripe Docs approach. They accept the space cost for consistent discoverability.

Option 3: Minimal TOC (Progress Bars)

The modern approach: represent sections as minimal bars, show details on-demand.

The Core Insight

A TOC serves two different functions:

1. Progress indicator: “Where am I in this document?”
2. Structure browser: “What sections exist and what are they about?”

These functions have different space requirements. Bars optimize for #1, text for #2.

Sub-Variants

Notion-Style Hover Expansion

Interaction:

• Default: Vertical bars representing sections
• Hover region: Bars expand to show full heading text
• Click: Jump to section

The Layout Shift Problem:

This sounds elegant but has a critical flaw:

Bars (compact):           Text (expanded):
│ ▃ (4px each)           Introduction        (20px)
│ ▃                      Getting Started     (20px)
│ ▅                      Configuration       (20px)
│ ▃                      Advanced Topics     (20px)
│ ▃                      Troubleshooting     (20px)

When bars expand to text, vertical positions shift because text requires more height than bars. You lose spatial tracking.

If you were hovering toward the 5th bar down, it might become the 8th line in the text list. Your spatial memory breaks.

Grok-Style Tooltips

Interaction:

• Default: Vertical bars
• Hover individual bar: Tooltip shows that heading only
• Click: Jump to section
• Bars remain bars (no expansion)

Pros:

• Zero layout shift
• Clean aesthetic
• Spatial positions remain stable
• Shows progress at a glance

Cons:

• Can’t scan full structure at once
• Tooltip interaction slower than reading a list
• Requires hover per item to see headings

Design Philosophy:

“Most navigation is ‘jump to a section I remember’, not ‘discover structure’. Optimize for the common case.”

Users typically interact with TOC in two modes:

• 80% of time: “I need to get to the deployment section” → tooltip is fine
• 20% of time: “What’s in this article?” → need overview

Hybrid: Bars + Overlay Escape Hatch

Interaction:

• Default: Grok-style bars with tooltips
• Button at top of TOC: Opens full text outline overlay
• Overlay provides complete structure when needed

Pros:

• No layout shift on common path (bar tooltips)
• Full structure available on-demand (overlay)
• Each UI optimized for its purpose
• User control over information density

Cons:

• Two interaction patterns to learn
• Slightly more implementation complexity
• Overlay might not be discoverable

Mobile Considerations

Desktop sidebar patterns fundamentally don’t translate to mobile:

• Text TOC: Usually hidden entirely, sometimes accordion
• Minimal bars: Can become floating button → overlay
• No TOC: Often the pragmatic mobile choice

The Spatial Stability Constraint

After comparing these approaches, one constraint emerged as critical:

Layout shift during interaction breaks user trust.

When UI elements move unpredictably (auto-collapsing branches, bar-to-text expansion), users:

1. Lose spatial orientation
2. Miss their click targets
3. Feel the interface is unstable
4. Develop learned helplessness

This makes Grok-style bars with optional overlay the most defensible approach:

• Primary interaction (tooltip) has zero shift
• Secondary interaction (overlay) is intentional, not accidental
• Spatial positions remain stable

Configuration Strategy

Different content types need different TOC strategies:

toc: {
  style: 'minimal-bars' | 'text' | 'none',

  // For minimal-bars style
  minimal: {
    showTooltips: true,
    allowOverlay: true,  // Show button for full outline
    showProgress: true,  // Highlight current section
  },

  // For text style
  text: {
    autoFollow: true,
    position: 'sidebar' | 'inline',
  },

  // Mobile behavior (applies to all styles)
  mobile: 'overlay' | 'none',
}

Recommended default: minimal-bars with overlay escape hatch.

Conclusion

The “right” TOC depends on your content and audience:

• Philosophy blogs (3-5 sections): No TOC or simple text
• Technical tutorials (10+ sections): Minimal bars with overlay
• API documentation (deep hierarchy): Text TOC with manual collapse
• Mobile-first blogs: No TOC, rely on in-content anchors

The lesson isn’t “bars are better than text” or vice versa. It’s:

Spatial stability > Information density.

Users tolerate less information (tooltips instead of full text) better than they tolerate unpredictable layout shifts.

When in doubt, optimize for the interaction that doesn’t move.

References

• Linear changelog: Pure bars, tooltip per item
• Notion: Bars with expansion (accepts layout shift)
• MDN: Full text sidebar (accepts space cost)
• Stripe Docs: Full text sidebar with auto-follow
• GitHub: No TOC (short-form content)

Each made different trade-offs based on their content characteristics and user needs.