webpack / webpack/webpack.js.org

[UX]: Add Active Section Highlighting to Docs Sidebar

Open
#8,323 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
MDX
Stars
2.3k
Forks
3.4k
Avg merge
13h 32m
Merged PRs (30d)
71

Description

Description

Currently, when reading through a documentation page (e.g., /output), the sidebar navigation on the left does not visually indicate which section the user is currently viewing. As the user scrolls through the main content, the sidebar remains static with no active state feedback, making it difficult to:

  1. Know where you are: There is no visual distinction (highlight, bold, color change, or animation) on the sidebar item corresponding to the section currently visible in the viewport.
  2. Jump to a desired section: Without a clear active indicator, users cannot quickly orient themselves within long documentation pages.
  3. Track scroll progress: When the main content is scrolled and a new section (e.g., "Entry" → "Output" → "Loaders") enters the viewport, the sidebar does not automatically scroll to keep the active item visible, nor does the active highlight transition from one subheading to another.

Current Behavior

  • The sidebar lists all page sections and subheadings (e.g., Entry, Output, Loaders, Plugins, Mode, etc.) as static links. Scrolling through the main content does not update any visual state in the sidebar.
  • There is no animation or transition effect when moving between sections.
Image

Proposed feature

  • As the user scrolls through the main documentation content, the sidebar should highlight the currently active section
  • The active highlight should smoothly transition from one section to the next as the user scrolls past section boundaries.
  • Clicking a sidebar item should scroll the main content to the corresponding section and immediately update the active state.

Inspo

The tailwind CSS docs implement this pattern effectively with a smooth scroll-tracking sidebar.(see on the right side of page--this page section.)

Results

This enhancement would significantly improve the reading and navigation experience on long documentation pages, especially for new users who are trying to orient themselves within the webpack documentation.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the documentation sidebar and the main content navigation entry points; the issue does not name specific files or tests. Trace how section links and scrolling currently work, then verify that scrolling and clicking update the active sidebar item, keep it visible, and transition between sections.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.