toc-generator
npx machina-cli add skill kostja94/marketing-skills/toc --openclawComponents: 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 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
<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
- 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
Source
git clone https://github.com/kostja94/marketing-skills/blob/main/skills/components/toc/SKILL.mdView on GitHub Overview
Guides the creation, optimization, and audit of table of contents for long-form content such as articles, guides, and whitepapers. It covers placement, heading structure, semantic HTML, and related SEO/UX practices to help readers navigate quickly and to boost search visibility.
How This Skill Works
It analyzes content type, length, and platform to propose a TOC structure, placement, and implementation. It prescribes heading rules (one h1 per page, h2 for major sections, h3 for subsections), unique IDs in kebab-case, and anchor links. It outputs a structured map including the TOC structure, heading/ID mappings, HTML/ARIA notes, and an SEO checklist.
When to Use It
- Adding a TOC to a long-form piece (1000+ words) to aid navigation.
- Auditing an existing article to improve structure, accessibility, and SEO with a TOC.
- Improving in-page navigation for long guides, whitepapers, or documentation.
- Implementing jump links and content outlines to boost user experience and CTR.
- Choosing TOC placement and behavior (after intro, top of article, or floating sidebar) for different devices.
Quick Start
- Step 1: Assess content type and length to determine TOC placement.
- Step 2: Draft heading structure (H1, H2, H3) and generate kebab-case IDs for headings.
- Step 3: Build a semantic nav with anchor links, ARIA labeling, and an SEO checklist; validate accessibility and mobile behavior.
Best Practices
- Use a single h1 per page; assign h2 for major sections and h3 for subsections with no skipped levels.
- Keep headings descriptive and long enough (15+ characters) to aid SEO and readability.
- Assign unique IDs in kebab-case for each heading and anchor TOC entries with clear keyword-focused text.
- Include a semantic nav with aria-label and a structured list; add a Schema.org TableOfContents when appropriate.
- Plan mobile-friendly behavior with accessible font sizes, touch targets, and optional collapsible sections.
Example Use Cases
- TOC for a 1,800-word guide on keyword research with multi-level headings.
- TOC for a 2,500-word whitepaper on AI in marketing with top and subheadings.
- TOC for a product documentation page covering Setup, Features, Troubleshooting.
- TOC for an on-page SEO best practices article with sections like Research, On-Page, and Tools.
- TOC for a case study article detailing problem, approach, results, and lessons learned.
