Table of Contents Feature

Introduction

The Table of Contents (TOC) feature for Maven Skin provides automatic generation of an interactive navigation structure for your documentation pages. It scans the page for headings and creates a hierarchical list that helps readers quickly navigate to sections of interest.

This feature is particularly useful for long-form documentation, API references, and blog posts where readers need to understand the page structure at a glance.

Key Features

Getting Started

Basic Setup

To add a table of contents to your page, include three things:

1. The TOC container div
2. The JavaScript file
3. The CSS stylesheet

HTML Structure

<div class="toc-container"></div>

<main>
  <h2>Section One</h2>
  <p>Content here...</p>
  
  <h2>Section Two</h2>
  <p>More content...</p>
</main>

Script Integration

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

Maven Velocity Template

For Maven Site integration, use the provided Velocity macros:

#parse('toc-macros.vm')

#setupTableOfContents()

$content

Configuration Options

The TOC generator accepts several configuration options:

Example Configuration

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

Customization

Styling

Customize the appearance by overriding CSS classes:

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

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

.toc-link:hover {
  color: #20c997;
}

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

Dark Mode

The TOC automatically adapts to dark mode. Customize it with:

@media (prefers-color-scheme: dark) {
  .toc-container {
    background-color: #2d2d2d;
    border-left-color: #66b3ff;
  }

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

Accessibility

Features

• Keyboard Navigation: Full support with Tab, Enter, and Space keys
• Screen Readers: Semantic HTML with proper heading hierarchy
• Focus Indicators: Clear focus rings for keyboard users
• High Contrast: Special styling for high contrast mode
• Reduced Motion: Respects user motion preferences

Browser Support

Advanced Usage

Multiple TOCs

Generate separate TOCs for different sections:

<section id="part1">
  <div class="toc-container"></div>
  <script>
    TOCGenerator.init({
      containerSelector: '#part1 .toc-container',
      headingSelector: '#part1 h2'
    });
  </script>
</section>

<section id="part2">
  <div class="toc-container"></div>
  <script>
    TOCGenerator.init({
      containerSelector: '#part2 .toc-container',
      headingSelector: '#part2 h2'
    });
  </script>
</section>

Conditional Display

Only show TOC if there are enough headings:

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

Troubleshooting

TOC Not Appearing

• Check that the page has at least 3 headings (or your configured minimum)
• Verify the container element exists with class toc-container
• Check browser console for JavaScript errors
• Ensure the script file is loaded correctly

Styling Not Applied

• Verify the CSS file is loaded in the Network tab
• Check for CSS specificity conflicts with other stylesheets
• Clear browser cache and rebuild
• Inspect element with DevTools to see actual styles

Smooth Scrolling Not Working

• Check browser support for smooth scrolling
• Verify smoothScroll: true in configuration
• Check for CSS scroll-behavior: auto overrides
• Test in different browsers to isolate the issue

Frequently Asked Questions

Q: Can I customize the colors?

A: Yes! The TOC uses standard CSS classes that you can override. See the Customization section for details.

Q: Does it work with my existing Maven Site setup?

A: Yes! The TOC is designed to integrate seamlessly with Maven Site. Just use the provided Velocity macros.

Q: Is it accessible?

A: Absolutely! The TOC is WCAG AA compliant with full keyboard navigation and screen reader support.

Q: Can I disable smooth scrolling?

A: Yes, set smoothScroll: false in the configuration.

Q: What file sizes are we talking about?

A: The JavaScript is ~3.5KB minified, and the CSS is ~2KB minified. Both are very lightweight.

Next Steps

Now that you understand the TOC feature, you can:

1. Add it to your Maven Skin templates
2. Customize the styling to match your brand
3. Configure options for your specific use case
4. Test across different devices and browsers
5. Monitor user feedback and improve