Table of Contents Feature

Overview

The Table of Contents (TOC) feature for Maven Skin provides automatic generation of an interactive, hierarchical navigation structure for your documentation pages. It scans your content for headings and creates a responsive, accessible TOC that helps readers navigate efficiently.

This feature is especially valuable for:

Long-form documentation pages
API reference documentation
Blog posts and articles
User guides and tutorials
Technical specifications
Change logs and release notes

Current Version: 1.0.0
License: MIT
Status: Production Ready

Features
Installation
Quick Start
Configuration
API Reference
Customization
Accessibility
Browser Support
Performance
Advanced Usage
Troubleshooting
FAQ

Features

Core Functionality

Automatic Heading Detection: Scans pages for h2-h6 headings automatically
Hierarchical Structure: Creates nested lists that match heading levels
Dynamic ID Assignment: Auto-generates IDs for headings without them
Smooth Scrolling: Animated navigation to sections (with fallback)
Active Section Highlighting: Current section highlighted during scroll
Responsive Design: Optimized for desktop, tablet, and mobile
Keyboard Navigation: Full support for Tab, Enter, and Arrow keys
Screen Reader Support: Semantic HTML and ARIA-friendly markup

User Experience

Clean, modern design with professional styling
Smooth hover effects and transitions
Visual feedback for active sections
Mobile-friendly navigation
Print-friendly layouts
Automatic dark mode adaptation
High contrast mode support
Reduced motion preference respect

Integration

Minimal dependencies (vanilla JavaScript)
Easy Maven Velocity template macros
Non-intrusive (no DOM manipulation beyond TOC)
Supports custom configurations
Progressive enhancement compatible
Works with or without jQuery

Installation

Step 1: Copy Files

Copy these files to your Maven Skin project:

src/main/resources/
├── js/
│   └── toc-generator.js
├── css/
│   └── toc-styles.css
└── META-INF/maven/
    └── toc-macros.vm

Step 2: Include in Templates

For Maven Velocity templates:

#parse('toc-macros.vm')

Step 3: Add to Your Pages

In your page template or inline:

#setupTableOfContents()

Or manually:

<link rel="stylesheet" href="css/toc-styles.css">
<div class="toc-container"></div>
<script src="js/toc-generator.js"></script>
<script>
  TOCGenerator.init();
</script>

Quick Start

Minimal Setup

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="css/toc-styles.css">
</head>
<body>
  <div class="toc-container"></div>

  <main>
    <h2>Section 1</h2>
    <p>Your content here...</p>

    <h2>Section 2</h2>
    <p>More content...</p>
  </main>

  <script src="js/toc-generator.js"></script>
  <script>TOCGenerator.init();</script>
</body>
</html>

Maven Integration

#parse('toc-macros.vm')

#setupTableOfContents()

$content

With Custom Configuration

TOCGenerator.init({
  headingSelector: 'h2, h3',
  minHeadings: 2,
  smoothScroll: true,
  highlightActiveSection: true
});

Configuration

Options Reference

Option	Type	Default	Description
`headingSelector`	string	`'h2, h3, h4, h5, h6'`	CSS selector for headings to include
`containerSelector`	string	`'.toc-container'`	CSS selector for TOC container
`minHeadings`	number	`3`	Minimum headings required to display TOC
`smoothScroll`	boolean	`true`	Enable smooth scrolling on link click
`highlightActiveSection`	boolean	`true`	Highlight current section during scroll

Configuration Examples

Basic Configuration

TOCGenerator.init();

Custom Heading Levels

TOCGenerator.init({
  headingSelector: 'h2, h3, h4'
});

Lower Minimum Threshold

TOCGenerator.init({
  minHeadings: 2
});

Disable Smooth Scrolling

TOCGenerator.init({
  smoothScroll: false
});

Disable Active Highlighting

TOCGenerator.init({
  highlightActiveSection: false
});

Full Custom Configuration

TOCGenerator.init({
  headingSelector: 'article h2, article h3',
  containerSelector: '#sidebar-toc',
  minHeadings: 2,
  smoothScroll: true,
  highlightActiveSection: true
});

API Reference

TOCGenerator Object

Methods

`TOCGenerator.init(options)`

Initializes the TOC generator with optional configuration.

Parameters: - options (Object, optional): Configuration object

Example:

TOCGenerator.init({
  minHeadings: 2,
  smoothScroll: true
});

`TOCGenerator.generate()`

Manually trigger TOC generation (called automatically by init).

Example:

// After adding new content dynamically
document.getElementById('main').innerHTML += newContent;
TOCGenerator.generate();

`TOCGenerator.extractHeadings()`

Extract headings from the document.

Returns: Array of heading objects

Example:

const headings = TOCGenerator.extractHeadings();
console.log(headings.length); // number of headings found

`TOCGenerator.buildTOCList(headings)`

Build nested TOC list from heading array.

Parameters: - headings (Array): Array of heading objects

Returns: HTML UL element

Example:

const headings = TOCGenerator.extractHeadings();
const list = TOCGenerator.buildTOCList(headings);

Customization

Styling

The TOC uses the following CSS classes for styling:

.toc-container        /* Main container */
.toc-title           /* Title element */
.toc-list            /* Main list */
.toc-link            /* TOC links */
.toc-link:hover      /* Hover state */
.toc-link.active     /* Active section */
.toc-link:focus      /* Focus state */

Custom Colors

/* Light theme */
.toc-container {
  background-color: #f8f9fa;
  border-left-color: #007bff;
}

.toc-link {
  color: #007bff;
}

.toc-link:hover {
  color: #0056b3;
  border-bottom-color: #0056b3;
}

.toc-link.active {
  color: #0056b3;
  border-left-color: #007bff;
}

Dark Mode

@media (prefers-color-scheme: dark) {
  .toc-container {
    background-color: #1e1e1e;
    border-left-color: #4da3ff;
  }

  .toc-link {
    color: #4da3ff;
  }

  .toc-link:hover {
    color: #66b3ff;
    border-bottom-color: #66b3ff;
  }

  .toc-link.active {
    color: #66b3ff;
    border-left-color: #4da3ff;
  }
}

High Contrast Mode

@media (prefers-contrast: more) {
  .toc-container {
    border-left-width: 6px;
    border-top: 2px solid currentColor;
    border-bottom: 2px solid currentColor;
  }

  .toc-link {
    text-decoration: underline;
  }

  .toc-link.active {
    font-weight: 700;
    border-left-width: 4px;
  }
}

Spacing and Layout

.toc-container {
  padding: 1.5rem;
  margin: 1.5rem 0;
}

.toc-list ul {
  padding-left: 1.5rem;
  margin: 0.25rem 0;
}

.toc-list li {
  margin: 0.5rem 0;
}

Custom Themes

Example: Green Theme

.toc-container {
  border-left-color: #28a745;
  background-color: #f0f8f4;
}

.toc-link {
  color: #28a745;
}

.toc-link.active {
  border-left-color: #20c997;
  color: #20c997;
}

Example: Red Theme

.toc-container {
  border-left-color: #dc3545;
  background-color: #fdf7f7;
}

.toc-link {
  color: #dc3545;
}

.toc-link.active {
  border-left-color: #c82333;
  color: #c82333;
}

Accessibility

WCAG Compliance

The TOC feature meets Web Content Accessibility Guidelines (WCAG) 2.1 Level AA standards:

✅ Perceivable: Clear visual hierarchy and focus indicators
✅ Operable: Full keyboard navigation support
✅ Understandable: Semantic HTML and clear link text
✅ Robust: Compatible with assistive technologies

Features

Keyboard Navigation

Key	Action
Tab	Move to next link
Shift+Tab	Move to previous link
Enter	Activate link (if using keyboard)
Space	Scroll to target (if focused)

Screen Reader Support

Semantic heading hierarchy maintained
Links have descriptive text
ARIA labels used appropriately
Skip links compatible

Visual Accessibility

High color contrast ratios (WCAG AA minimum)
Clear focus indicators (3px outline)
Hover states visually distinct
Text resize supported

Motion Accessibility

@media (prefers-reduced-motion: reduce) {
  .toc-link {
    transition: none;
  }

  html {
    scroll-behavior: auto;
  }
}

Browser Support

Browser	Version	Support	Notes
Chrome	60+	✅ Full	Modern features fully supported
Firefox	55+	✅ Full	Modern features fully supported
Safari	12+	✅ Full	Modern features fully supported
Edge	15+	✅ Full	Modern features fully supported
IE 11	-	⚠️ Basic	Limited smooth scroll support

Feature Support by Browser

Feature	Chrome	Firefox	Safari	Edge	IE 11
Smooth Scroll	✅	✅	✅	✅	❌
IntersectionObserver	✅	✅	✅	✅	❌
CSS Grid	✅	✅	✅	✅	❌
Dark Mode	✅	✅	✅	✅	❌
High Contrast	✅	✅	✅	✅	❌

Performance

Bundle Size

File	Minified	Gzipped
toc-generator.js	3.5 KB	1.2 KB
toc-styles.css	2.0 KB	0.6 KB
Total	5.5 KB	1.8 KB

Optimization Techniques

Passive event listeners (scroll events)
Single DOM traversal
Cached querySelector results
Efficient CSS selectors
Minimal reflows/repaints
Debounced scroll calculations

Performance Tips

Limit Heading Levels: Use headingSelector: 'h2, h3' instead of all levels
Set Appropriate minHeadings: Prevents TOC on pages with few headings
Defer Script Loading: Use defer attribute on script tag
Minify Resources: Minify in production builds
Cache Aggressively: Set appropriate cache headers

Advanced Usage

Multiple TOCs

Generate separate TOCs for different content sections:

<section id="part1">
  <div class="toc-container" data-section="part1"></div>
  <h2>Section 1.1</h2>
  <h2>Section 1.2</h2>
</section>

<section id="part2">
  <div class="toc-container" data-section="part2"></div>
  <h2>Section 2.1</h2>
  <h2>Section 2.2</h2>
</section>

<script>
TOCGenerator.init({
  containerSelector: '[data-section="part1"]',
  headingSelector: '#part1 h2'
});

TOCGenerator.init({
  containerSelector: '[data-section="part2"]',
  headingSelector: '#part2 h2'
});
</script>

Dynamic Content

For dynamically added content:

// Add new content
document.getElementById('content').innerHTML += newHTML;

// Regenerate TOC
TOCGenerator.generate();

Filtering Headings

Exclude specific headings from TOC:

<h2>Include in TOC</h2>
<h2 class="toc-exclude">Exclude from TOC</h2>

TOCGenerator.init({
  headingSelector: 'h2:not(.toc-exclude)'
});

Conditional Display

Only show TOC if minimum headings met:

#parse('toc-macros.vm')
#conditionalTableOfContents(2)

Custom Heading Extraction

Extend heading detection:

const headings = TOCGenerator.extractHeadings();
const filtered = headings.filter(h => h.level <= 3);
const list = TOCGenerator.buildTOCList(filtered);

Troubleshooting

Common Issues

Issue: TOC Not Appearing

Possible Causes: - Page has fewer than minimum headings - Container element missing or selector wrong - Script not loaded - JavaScript error in console

Solutions: 1. Check page has at least 3 headings (or your configured minimum) 2. Verify .toc-container element exists 3. Check Network tab - confirm script loads 4. Open DevTools Console - check for errors 5. Verify minHeadings configuration

Issue: Styling Not Applied

Possible Causes: - CSS file not loaded - CSS specificity conflicts - Cache issues - Browser cache

Solutions: 1. Check Network tab - confirm CSS loads 2. Inspect element - see actual styles 3. Check for conflicting CSS rules 4. Hard refresh browser (Ctrl+Shift+R) 5. Clear cache and rebuild

Issue: Smooth Scrolling Not Working

Possible Causes: - Browser doesn’t support smooth scroll - CSS override forcing scroll-behavior: auto - JavaScript error - smoothScroll: false configured

Solutions: 1. Check browser support 2. Look for CSS overrides 3. Check browser console for errors 4. Verify config: smoothScroll: true 5. Try with different browser

Issue: Active Section Not Highlighting

Possible Causes: - highlightActiveSection: false - Scroll listener not attached - Headings don’t have IDs - JavaScript error

Solutions: 1. Verify highlightActiveSection: true 2. Check console for JavaScript errors 3. Ensure headings have IDs 4. Check Network tab - script loads 5. Test in different browser

Issue: Mobile Display Issues

Possible Causes: - Viewport meta tag missing - CSS media queries not triggered - Touch events not handled - Font size too large

Solutions: 1. Verify viewport meta tag present 2. Test responsive view in DevTools 3. Check CSS media queries (768px breakpoint) 4. Test on actual mobile device 5. Adjust font sizes if needed

Debug Tips

Enable Debug Logging:

// Add to browser console
TOCGenerator.config.debug = true;
TOCGenerator.init();

Check Extracted Headings:

const headings = TOCGenerator.extractHeadings();
console.table(headings);

Verify Container:

console.log(document.querySelector('.toc-container'));

Test Selector:

console.log(document.querySelectorAll('h2, h3, h4, h5, h6'));

FAQ

General Questions

Q: Will TOC work with my existing Maven Site?
A: Yes! It integrates seamlessly. Just parse the macros and use #setupTableOfContents().

Q: Can I use TOC without Maven?
A: Absolutely! It’s pure HTML/CSS/JavaScript. Skip the Velocity part.

Q: Is there a jQuery dependency?
A: No! It’s vanilla JavaScript, no external dependencies.

Q: Does it work with static site generators?
A: Yes! Any HTML page can use it.

Configuration Questions

Q: How do I change the TOC title?
A: Edit the .toc-title text in your template or CSS.

Q: Can I customize colors?
A: Yes! Override the CSS classes. See Customization section.

Q: How do I hide TOC on small screens?
A: Add media query: @media (max-width: 768px) { .toc-container { display: none; } }

Q: Can I disable smooth scrolling?
A: Yes: TOCGenerator.init({ smoothScroll: false })

Functionality Questions

Q: What if a heading has no ID?
A: IDs are auto-generated (e.g., heading-0, heading-1).

Q: Can I exclude specific headings?
A: Use :not() selector: headingSelector: 'h2:not(.skip)'

Q: Does it work with SPA (Single Page App)?
A: Call TOCGenerator.generate() after new content loads.

Q: Can I have multiple TOCs on one page?
A: Yes! Initialize separately with different selectors.

Accessibility Questions

Q: Is it accessible?
A: Yes! WCAG AA compliant with full keyboard support.

Q: Does it work with screen readers?
A: Yes! Semantic HTML and ARIA-compatible.

Q: How do I disable animations for users with motion sensitivity?
A: Automatically respected via prefers-reduced-motion.

Browser Questions

Q: Why doesn’t IE 11 smooth scroll?
A: IE 11 doesn’t support CSS scroll-behavior: smooth. It still scrolls, just instantly.

Q: Does it work on mobile?
A: Yes! Fully responsive and touch-friendly.

Q: Which browsers should I test?
A: Chrome, Firefox, Safari, Edge (modern versions) are recommended.

Performance Questions

Q: Will it slow down my site?
A: No! ~1.8 KB gzipped with minimal overhead.

Q: Should I minify the files?
A: Yes, in production. Use Maven minify plugin.

Q: Can I lazy-load the script?
A: Yes! Use defer or load after DOM ready.

Integration Questions

Q: How do I integrate with Maven Site Plugin?
A: Use the provided Velocity macros in your skin templates.

Q: Can I use custom Velocity variables?
A: Yes! Modify toc-macros.vm as needed.

Q: Does it work with Doxia decorators?
A: Yes! Works with standard Maven Site setup.

Version History

Version 1.0.0 (Current)

Initial release
Automatic heading detection
Hierarchical nesting
Smooth scrolling and active highlighting
Full accessibility support
Responsive design
Dark mode support
Comprehensive documentation

Support and Contributions

Getting Help

Examples: See toc-example.html for a working example page
Site: This page is the canonical TOC reference (formerly TOC-FEATURE.md / TOC-README.md)
Issues: Report bugs on GitHub Issues

Contributing

Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request

License

MIT License - Feel free to use in personal and commercial projects.

Changelog

Last Updated: 2026-05-14
Maintained by: Verron.pro Team
Repository: https://github.com/verronpro/maven-skin