Table of Contents

​

Overview

​

Features

• Active section highlighting - Shows your current position in the document
• Collapsible subsections - Expand/collapse nested sections to reduce clutter
• Keyboard and mouse navigation - Multiple ways to interact
• Smooth scrolling - Animated scroll to selected sections
• Auto-expand on navigation - Opens relevant sections when jumping to headings
• Persistent state - Remembers which sections you’ve expanded
• Hash change support - Updates when URL hash changes

​

User Interface

​

Structure

1. First Top-Level Section ▼
   1.1 Subsection
   1.2 Subsection
2. Second Top-Level Section ▼
   2.1 Subsection
       2.1.1 Nested subsection
3. Third Top-Level Section ▼

​

Visual Indicators

• ▼ Toggle arrow - Click to expand/collapse subsections
• Bold text - Active top-level section
• Highlight background - Currently visible section
• Indentation - Shows section hierarchy

​

Collapsible Sections

• Collapsed - Shows only the parent heading
• Expanded - Shows all subsections
• Auto-collapse - Enabled when page has 4+ level-1 sections and enough total sections

​

Interactions

​

Clicking Links

1. Click a section link - Navigates to that section
2. ToC highlights the active section - Shows where you are
3. Parent sections expand - Reveals subsection hierarchy
4. Smooth scroll - Page scrolls smoothly to the heading

​

Toggle Buttons

• Collapsed → Click to expand and show subsections
• Expanded → Click to collapse and hide subsections
• State persists - Stays expanded until you collapse it

​

Keyboard Navigation

• Click any ToC link - Standard keyboard navigation works
• Tab - Move between ToC links
• Enter - Navigate to selected section

​

Pinned/Unpinned

• Pinned - Always visible in sidebar
• Unpinned - Hidden, can be toggled

​

Automatic Active Section Tracking

1. Scroll observer monitors your position (implemented separately)
2. Active section changes as you scroll
3. ToC updates to highlight current section
4. Parent sections expand if needed
5. ToC scrolls to keep active section visible

​

Configuration

​

Collapse Threshold

{
  "CitizenTableOfContentsCollapseAtCount": 12
}

• Page has 4+ level-1 sections AND
• Total section count ≥ CitizenTableOfContentsCollapseAtCount

​

CSS Classes

ACTIVE_SECTION_CLASS = 'citizen-toc-list-item--active'
ACTIVE_TOP_SECTION_CLASS = 'citizen-toc-level-1--active'
EXPANDED_SECTION_CLASS = 'citizen-toc-list-item--expanded'
TOP_SECTION_CLASS = 'citizen-toc-level-1'
LINK_CLASS = 'citizen-toc-link'
TOGGLE_CLASS = 'citizen-toc-toggle'

​

Technical Implementation

​

Architecture

const tableOfContents = new TableOfContents({
  container: document.getElementById('mw-panel-toc-list'),
  onHeadingClick: (id) => { /* handle click */ },
  onHashChange: (id) => { /* handle hash change */ },
  onToggleClick: (id) => { /* handle toggle */ },
  onTogglePinned: () => { /* handle pin toggle */ },
  window: window,
  document: document,
  mw: mw
});

​

Key Methods

​

Section Management

// Activate a section
tableOfContents.activateSection('toc-section-id');

// Deactivate all sections
tableOfContents.deactivateSections();

// Change active section (deactivate + activate)
tableOfContents.changeActiveSection('toc-section-id');

​

Expand/Collapse

// Expand a section
tableOfContents.expandSection('toc-section-id');

// Collapse sections
tableOfContents.collapseSections(['toc-section-id']);

// Toggle a section
tableOfContents.toggleExpandSection('toc-section-id');

// Get expanded section IDs
const expanded = tableOfContents.getExpandedSectionIds();

​

Scrolling

// Scroll active section into view
tableOfContents.scrollToActiveSection('toc-section-id');

const scrollBehavior = this.prefersReducedMotion() ? undefined : 'smooth';

​

Dynamic Reloading

tableOfContents.reloadTableOfContents(sections).then(() => {
  console.log('ToC reloaded with', sections.length, 'sections');
});

1. Saves expanded section IDs
2. Re-renders ToC HTML from section data
3. Re-expands previously expanded sections
4. Restores active section highlighting

​

Section Data Format

{
  toclevel: 1,
  anchor: 'Section_Title',
  line: 'Section Title',
  number: '1',
  index: '1',
  'is-top-level-section': true,
  'is-parent-section': true,
  'array-sections': [ /* subsections */ ]
}

​

Event Handling

​

Hash Changes

window.addEventListener('hashchange', () => {
  // Parse hash from URL
  // Find matching ToC item
  // Expand and activate section
});

​

Click Events

container.addEventListener('click', (e) => {
  const tocSection = e.target.closest('.citizen-toc-list-item');
  
  if (e.target.closest('.citizen-toc-link')) {
    // Handle link click
  }
  
  if (e.target.closest('.citizen-toc-toggle')) {
    // Handle toggle click
  }
});

​

Accessibility

​

ARIA Attributes

<button class="citizen-toc-toggle" 
        aria-expanded="false"
        aria-label="Toggle Section subsection">
  ▼
</button>

​

Keyboard Support

• Tab navigation - All links and buttons are focusable
• Enter/Space - Activate links and buttons
• Focus visible - Clear visual focus indicators

​

Reduced Motion

if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
  // Disable smooth scrolling
  // Use instant scroll instead
}

​

Integration with Other Features

​

Section Observer

// Section observer calls changeActiveSection when scrolling
sectionObserver.on('active-section-changed', (sectionId) => {
  tableOfContents.changeActiveSection(`toc-${sectionId}`);
});

​

Collapsible Sections

• ToC navigation still works
• Clicking ToC link expands collapsed sections
• hidden="until-found" allows browser to auto-expand

​

Sticky Header

• Scroll calculations consider header height
• Active section detection compensates for fixed header

​

Best Practices

​

Customization

​

Styling

.citizen-toc-list-item--active {
  background-color: var(--your-color);
  font-weight: bold;
}

.citizen-toc-toggle {
  /* Custom toggle button style */
}

​

Behavior

// Listen for ToC events
document.addEventListener('citizen.toc.section-activated', (e) => {
  console.log('Section activated:', e.detail.sectionId);
});

​

Troubleshooting

​

ToC Not Appearing

1. Check that page has headings (h2, h3, etc.)
2. Verify mw-panel-toc-list container exists
3. Check that skins.citizen.scripts module loaded

​

Active Section Not Highlighting

1. Ensure section observer is running
2. Check that ToC section IDs match page heading IDs
3. Verify no JavaScript errors in console

​

Sections Not Expanding

1. Check that toggle buttons have correct classes
2. Verify ARIA attributes are set correctly
3. Ensure click event listeners are attached

​

Performance Considerations

• Efficient DOM queries - Uses getElementById and closest()
• Event delegation - Single click listener on container
• Throttled updates - Section activation is debounced
• Smooth scroll - Hardware-accelerated when supported
• Lazy initialization - Only activates when ToC exists on page