- Reorganized Customizer structure for improved clarity and maintainability
- Introduced consistent default values for all settings to ensure stable fallbacks
when no user preferences are defined
- Refactored scroll-driven TOC implementation:
- Optimized scroll handling using requestAnimationFrame
- Reduced layout thrashing and unnecessary DOM reads
- Improved heading detection logic (deterministic viewport trigger)
- Enhanced positioning logic (responsive alignment + sidebar awareness)
- Improved footer collision handling for more robust layout behavior
- Added optional IntersectionObserver-based TOC implementation:
- Event-driven alternative to scroll-based approach
- Currently not enabled by default
- May not be supported long-term due to less deterministic behavior
- General cleanup and internal consistency improvements
chore: bump version to 2.4.0
The floating TOC positioning logic assumed a correct sidebar reference
when calculating the horizontal offset. However, the selector used
(`aside, .sidebar, #secondary`) could match non-layout elements such as
hidden containers, mobile sidebars, or unrelated widgets.
This resulted in incorrect `getBoundingClientRect()` values and caused
the TOC to be positioned too far left or right, depending on which
element was matched.
Solution:
- Introduced a `getRealSidebar()` helper to dynamically detect the
visually relevant sidebar element.
- Filters out non-visible or irrelevant elements based on size.
- Selects the right-most valid candidate, ensuring correct layout context.
- Uses the actual gap between content and sidebar to position the TOC
symmetrically on the opposite side of the content.
Additional improvements:
- Cached sidebar lookup to avoid repeated DOM queries during scroll.
- Stabilized gap calculation with clamping to prevent layout drift.
Result:
The TOC now consistently aligns with the content column and mirrors
the sidebar spacing correctly across different layouts and breakpoints.
Fix incorrect TOC alignment caused by outdated DOM selector in toc.js.
The content reference element changed during layout refactor, breaking
position calculations for the floating TOC.
Updated contentColumn selector to use .main-wrapper/.container fallback,
ensuring correct left offset and responsive positioning.
Also adds a more robust fallback chain to prevent future regressions
when layout structure changes.
Dome