Multilingual Scroll Spy in Jekyll Posts

Improving UX with Scroll-Aware TOC

After building a multilingual table of contents (ToC) in the previous article, it's time to enhance usability further. A scroll spy highlights the current section in the navigation menu as the user scrolls, making it easier to track their reading position—especially in multilingual content where users might skim differently based on text length or structure.

We'll use the modern IntersectionObserver API for a performance-friendly implementation that avoids scroll event bottlenecks.

Understanding the Scroll Spy Behavior

The goal is to dynamically highlight the currently visible section in the ToC. This involves:

• Detecting when a heading (h2, h3) enters the viewport
• Finding the corresponding link in the ToC
• Adding/removing an active class to style the link

Step 1: Update Your TOC Markup

In your _includes/toc.html, make sure the anchor tags have a consistent structure. Each should wrap a heading's ID:

  <li><a href="#section-id">Section Title</a></li>

No changes are needed here if you followed the previous guide.

Step 2: Add Scroll Spy JavaScript

Below the script that generates your ToC list, add this code:

{% raw %}

{% endraw %}

Step 3: Style the Active TOC Link

Add this to your CSS (e.g., in assets/css/main.css):

#toc-list a.active {
  font-weight: bold;
  color: #007acc;
  text-decoration: underline;
}

You can also add indicators like a border or icon if desired.

Step 4: Adapt to Multiple Languages

Because we previously structured our headings and ToC links based on the page language, this scroll spy works seamlessly across locales. The anchor structure doesn’t change; the labels are already localized via Liquid and data files.

Make sure all headings that appear in the ToC have an id attribute and visible text content in the appropriate language.

Performance Considerations

The IntersectionObserver is highly efficient because it avoids the costly scroll event. It's also widely supported by modern browsers. For legacy fallback (e.g., IE), you could include a polyfill, though this is optional for most projects today.

Testing Across Languages

• Switch between English, Spanish, or other available translations
• Scroll through the post and observe the ToC highlight update
• Ensure ToC labels match the language set in front matter

Making Scroll Spy Reusable

Encapsulate the scroll spy logic in a separate include, like _includes/scroll-spy.html, and call it in your layout:

{% raw %}
{% include scroll-spy.html %}
{% endraw %}

This ensures DRY principles and centralized control over behavior.

Enhancing Accessibility

Add aria-current="true" to the active link for screen readers:

link.classList.toggle('active', match);
if (match) {
  link.setAttribute('aria-current', 'true');
} else {
  link.removeAttribute('aria-current');
}

Use Cases

• Documentation sites with multiple headings
• Academic articles with complex structures
• Multilingual how-to guides

Next Steps

This scroll spy is a powerful addition to your multilingual Jekyll site. To make it even better, consider syncing the URL hash to reflect the active section for deep-linking support or generating dynamic breadcrumbs. We'll explore this in the next article.

Conclusion

Combining multilingual content with interactive UI like scroll spy improves both accessibility and user experience. By relying on native browser APIs and Liquid templating, we’ve created a future-proof system for global websites.

In the next article, we’ll build on this by making scroll position affect the browser’s URL hash and allow users to share section-specific links across languages.