asyncapi / asyncapi/website

[Bug] TOC active section highlight breaks after navigating between pages

Open
#4,845 8 comments 0 reactions 0 assignees View on GitHub
bug stale triaged
Dominant language
TypeScript
Stars
716
Forks
1.2k
Avg merge
1d 12h
Merged PRs (30d)
35

Description

### Describe the bug you found in AsyncAPI Docs.

## 🐛 Docs TOC active section highlight breaks after navigating between pages

### Why do we need this improvement?
Currently, the **“On this page” (Table of Contents)** highlighting works correctly when a docs page is loaded for the first time. However, after navigating to another docs page using client-side navigation and then returning (or moving to the next page), the **active section highlighting stops working completely**.

Observed behavior:
- On initial page load, the current section is highlighted correctly (purple).
- After navigating to another docs page, no TOC item is highlighted.
- Navigating back to the previous page does not restore the highlight.
- Page reload fixes the issue temporarily.

This negatively impacts usability and makes it harder for users to understand their current position within long documentation pages.

---

### How will this change help?
Fixing this issue will:
- Ensure the TOC correctly highlights the active section across docs navigation.
- Improve readability and navigation consistency in the documentation.
- Align expected behavior when moving between docs pages using client-side routing.

---

### Root cause (technical context)
The TOC relies on `react-scrollspy`, which attaches scroll listeners and caches DOM references on mount.
Since the Docs layout persists across client-side route changes, the TOC component is not remounted when navigating between docs pages, leaving `react-scrollspy` in a stale state.

---

### 🎥 Problem Video
The following video demonstrates the issue:
- TOC highlight works on first load
- Highlight disappears after navigating to another docs page
- Highlight does not recover when navigating back

https://github.com/user-attachments/assets/15a3e501-3cde-49d1-9a0b-985493bfa7de

---

### ✅ Solved Video
The following video demonstrates the expected / fixed behavior:
- TOC highlight updates correctly after navigation
- Highlight persists when navigating between docs pages
- Behavior remains consistent without a full page reload

https://github.com/user-attachments/assets/0c75c9ff-566f-4244-9ad8-366e99d677dc

---

### How could it be implemented/designed?
A possible fix is to **force the TOC component to reinitialize on route change**, for example:
- Remounting the TOC component when the route changes (e.g., by keying it to `router.asPath`), or
- Explicitly resetting the Scrollspy lifecycle when navigating between docs pages.

---

### Alternatives
If forcing a remount is not preferred:
- The TOC logic could explicitly reattach Scrollspy listeners on route change.
- Scrollspy observers could be cleaned up and reinitialized when the content changes.

---

### Attach any resources that can help us understand the issue.

Image

Image

Image

### Code of Conduct

- I agree to follow this project's Code of Conduct

### Are you willing to work on this issue ?

Yes, I am willing to submit a PR for this issue.

Contributor guide

Open the contributing guide

Research direction

Locate the Docs TOC component and its react-scrollspy usage, then inspect how the persistent Docs layout handles client-side route changes. Reproduce navigation between documentation pages and verify that the active section highlight is restored without a full reload.

Written by the indexing model from the issue text.

Assessment

Tech stack
nextjs, react, typescript
Domain
documentation, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.