Tables of contents make long documents navigable. According to Nielsen Norman Group, users scan TOCs to decide what to read. Well-structured TOCs improve usability dramatically and boost SEO with rich snippets.
TOC Best Practices
| Guideline | Why |
|---|---|
| Include H2 and H3 only | Deeper levels clutter without value |
| Show hierarchy via indentation | Visual structure aids scanning |
| Link every entry | Readers expect clickable navigation |
| Use descriptive headings | "API Authentication" beats "Introduction" |
Auto-Generation Tools
| Tool | Best For |
|---|---|
| markdown-toc | Markdown files |
| Docusaurus | Documentation sites |
| Tocbot (JS) | Dynamic web pages |
| Hugo/Jekyll | Static sites |
Common Mistakes
- Manual TOCs (become outdated instantly)
- Generic headings ("Overview" tells nothing)
- Including every H4-H6 (overwhelming)
- Broken anchor links (test every entry)
FAQ
How deep should TOC go?
Three levels maximum. H2, H3, and occasionally H4. More creates noise.
When to skip TOC?
Documents under 5 pages don't need one. Scale TOC detail to document length.
Can AI help?
Yes, River's TOC Generator creates linked tables of contents from your headings automatically.