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 product marketing context first:
If
.claude/product-marketing-context.md
or
.cursor/product-marketing-context.md
exists, read it for content structure.
Identify:
Content type
Blog article, guide, whitepaper, documentation
Length
TOC most valuable for 1000+ word content
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
per page
for major sections
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
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