Fixes sidebar flashing and rebuilding on every nav click

[veejask-41]

Closes: #461

The Issue

The documentation sidebar was causing severe performance and user experience problems. Every time a user clicked a link, the browser had to download and parse a massive HTML payload, most of which was just the sidebar itself. This resulted in sluggish page loads and heavy network transfers.

Additionally, there was a visible layout shift (a "flash") on every load: the server would render all sidebar sections expanded, and client-side JavaScript would quickly collapse the inactive ones after the page painted. Finally, because soft navigation wasn't enabled, every click was a hard page reload. This meant users constantly lost their sidebar scroll position and any manually expanded sections whenever they navigated.

A significant portion of the page bloat was caused by developer HTML comments inside the navigation template, which were being duplicated in the final output for every single navigation item. The rest of the bloat came from the server rendering the full navigation trees for every product and every inactive version, only to hide them using CSS.

---

The Fix

1. Trimming the Payload

• Removed Developer Comments from Output: Converted the standard HTML comments in the navigation templates into Jinja comments. This keeps the annotations visible for developers in the source code but prevents the static site generator from shipping them to the browser.
• Pruned Hidden Content: Stopped rendering the DOM elements for inactive versions and products that the user wasn't currently viewing. Non-active top-level sections now render as simple links to their respective overview pages rather than loading their entire subtrees into the document.
• Shifted to Build-Time Data: Because the version dropdown and search scoping previously relied on reading that hidden DOM to function, Created a lightweight JSON index generated during the build step. The JavaScript now reads from this file and a simple data attribute, allowing us to safely drop the hidden HTML without breaking version switching or search filtering.

2. Eliminating the Visual Flash

• Server-Side State Rendering: Moved the logic that determines which sidebar sections should be collapsed from the post-load JavaScript directly into the Jinja templates. The server now calculates and emits the exact, final state for the navigation toggles, meaning the sidebar paints at its correct height immediately with no visual jumping.

3. Enabling Seamless Navigation

• Enabled Soft Navigation: Turned on MkDocs Material's instant loading feature so navigating between pages swaps out the content dynamically rather than triggering a hard browser reload.
• Updated Event Listeners: Rewired custom JavaScript handlers to hook into Material's page-swap observable rather than the standard initial DOM load event. This ensures custom behaviors (like code copying and external link routing) continue to work after the first click.
• Preserved Sidebar State: Because the instant loading mechanism replaces the container that holds the sidebar, Added a state bridge. It captures the sidebar's scroll position and expanded toggles just before a user clicks a link, and reapplies them immediately after the new page loads. This makes the sidebar appear completely static and untouched across navigations.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d8118591-c025-4c3e-8d39-08f5be358e38

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}