Table of Contents (TOC)

Generates a dynamic table of contents from headings inside one or more rich text blocks.

Pupolate a TOC from multiple rich text instances. Supports multiple independent TOCs via blx-id and now lists both H2 and H3, with proper indentation.

How it works

Gathers all H2 and H3 inside of [blx-el="toc-rich-text"].
Groups them in order they appear.
H3s become nested under their preceding H2, depending on the CSS added.
Each TOC instance only processes rich text blocks with a matching [blx-id="IDENTIFIER"].
Smooth scroll offset applies (100px by default).

1. Add Script

Add this <script> inside the before </body> tag of your page or project.
‍

<script defer src="https://cdn.jsdelivr.net/gh/codeandwander/blx@v1.0.2/packages/toc/index.js"></script>

2. Add CSS

Add the CSS to the <head> or custom code inside the project.
‍

[blx-el="toc-item"] a {
  text-decoration: none;
  color: inherit;
  transition: text-decoration-color 0.2s ease;
}

[blx-el="toc-item"] a:hover {
  text-decoration: underline;
  text-underline-offset: 2px;
}

/* Nested H3 style */
.toc-sublist {
  margin: 4px 0 0 16px;
  padding: 0;
  list-style: none;
}

.toc-sublist [blx-el="toc-item"] a {
  opacity: 0.8;
  font-size: 0.95em;
}

3. Add Required attributes

  • blx-el="toc" - add to the main TOC wrapper
  • blx-el="toc-list" - add to the <ul>
  • blx-el="toc-item" - add to the <li>
  • blx-el="toc-rich-text" - add to the rich text you want to use as sources, you can add multiple

Additional Attributes

  • blx-id="IDENTIFIER" - optional, if using more then one TOC per page group all blx-el attributes by adding the same id to each one of them.

Accessibility

BLX TOC includes several accessibility features:

Automatic features

  • Unique IDs - Headings without IDs are automatically assigned unique, URL-friendly slugs based on their text content.
  • Keyboard navigation - All TOC links are standard anchor elements, fully accessible via keyboard.
  • Smooth scrolling - Scroll behaviour is smooth with a configurable offset (100px default) to account for fixed headers.

Best practices

  • Use semantic heading hierarchy (H2, H3) in your rich text content.
  • Ensure heading text is descriptive and meaningful.
  • The TOC automatically reflects the document structure, helping users understand content organisation.

Tip: Use blx-id to create multiple independent TOCs on the same page, each linked to different rich text blocks. This is useful for long-form content with distinct sections.