/toc

name: toc-generator
description: When the user wants to add, optimize, or audit table of contents (TOC) for long-form content. Also use when the user mentions "TOC," "table of contents," "table of contents for article," "article TOC," "jump links," "content outline," "article navigation," "in-page navigation," "add TOC to blog," or "TOC for long content." For article SEO template, use article-page-generator.
metadata:
  version: 1.0.1

Components: Table of Contents (TOC)

Guides TOC implementation for long-form articles, guides, and whitepapers. TOCs improve UX and SEO by enabling quick navigation and reducing bounce rates.

**When invoking**: On **first use**, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for content structure.

Identify: 1. **Content type**: Blog article, guide, whitepaper, documentation 2. **Length**: TOC most valuable for 1000+ word content 3. **Platform**: Web, mobile, both

Placement Strategies

| Placement | Best For | Pros | Cons | |-----------|----------|------|------| | **After intro** | Most articles | Natural flow; visible early | Can scroll out of view | | **Floating sidebar** | Very long content | Always visible | More complex; mobile challenges | | **Collapsible** | Long articles | Less intrusive | May be overlooked | | **Top of article** | Mobile-first | Accessible on all devices | Takes space |

Technical Implementation

Heading Structure

• One `<h1>` per page
• `<h2>` for major sections
• `<h3>` for subsections; avoid skipping levels
• Headings >=15 characters for SEO

Jump Links

• Assign unique IDs to headings (e.g., `id="keyword-optimization"`)
• Use kebab-case for IDs
• Link TOC entries via anchor tags (`#section-id`)
• Descriptive anchor text; include target keywords naturally

Semantic HTML

<nav aria-label="Table of contents">
  <ol>
    <li><a href="#section-1">Section Title</a></li>
  </ol>
</nav>

SEO Best Practices

| Practice | Purpose | |----------|---------| | **Schema.org TableOfContents** | Help search engines understand structure | | **Keywords in headings** | Natural integration; avoid stuffing | | **Jump links in SERP** | Google may feature TOC links; increases CTR; see **serp-features** |

UX Guidelines

Visibility & Interaction

• Clear visual hierarchy; indent nested items
• Highlight current section when scrolling (optional)
• Smooth scroll behavior for jump links

Mobile

• Minimum 16px font size
• Touch targets >=44x44px
• Responsive layout; consider collapsible on small screens

Accessibility

| Requirement | Practice | |-------------|----------| | **ARIA** | `aria-label="Table of contents"` on nav | | **Keyboard** | All links keyboard-accessible | | **Screen readers** | Proper heading structure; TOC aids skimming |

Output Format

• **TOC structure** (sections, nesting)
• **Heading/ID mapping** suggestions
• **HTML/ARIA** notes
• **SEO** checklist

Related Skills

• **tab-accordion**: Collapsible TOC uses same disclosure pattern; details/summary implementation
• **heading-structure**: TOC built from heading structure
• **content-optimization**: H2 structure, lists, tables for Featured Snippets
• **featured-snippet**: Featured Snippet optimization; TOC supports snippet structure
• **serp-features**: SERP features; jump links in results
• **article-page-generator**: TOC common in long-form article pages