Layout: RHS "On this page" TOC truncates on long lectures; LHS sidebar crowded against content

[mmcky]

Summary

On long lectures with a deep section/subsection structure, the right-hand "On this page" TOC does not show all sections at default font size on a laptop screen. Hovering over the RHS TOC and scrolling causes the main content to scroll instead of the TOC, so the hidden sections remain unreachable from the RHS panel. Separately, the left-hand sidebar feels visually crowded against the main text.

Example

https://python.quantecon.org/prob_matrix.html

Reported at default font size on a laptop. The RHS "On this page" panel only shows section links up to roughly 8.7–8.8; sections from 8.9 onwards (including section 8.17 specifically called out) are not visible.

Note: the screenshot from the original report shows the lecture rendered with the LHS series TOC (Tools and Techniques / Elementary Statistics) and the RHS "On this page" panel — the RHS panel cuts off well before reaching all sections of the lecture.

Issues

1. RHS "On this page" TOC overflow

• The RHS TOC does not show all sections when the lecture has many of them.
• Natural user instinct: hover over the RHS panel and scroll. But scrolling there scrolls the main content instead of the RHS panel — so sections below the fold remain unreachable from the RHS.
• The RHS TOC should be independently scrollable when its content overflows the viewport, or it should adapt its layout/density so all sections fit.

2. LHS sidebar crowding

• At this screen size, the LHS sidebar sits hard against the main text with no whitespace between them, making the layout feel cramped.
• Options to explore:
  • Add a margin/gutter between the LHS sidebar and the main content
  • Change the LHS background from grey to white so the boundary is softer
  • Both

3. Possible responsive priority system (proposal)

A possible design direction worth exploring: assign layout priorities to the three columns so the layout adapts to available width.

• Priority 1 (always present): Main content
• Priority 2: LHS series TOC
• Priority 3 (collapses first): RHS "On this page"

Behaviour: when the LHS TOC is open and there isn't enough width, the main content shifts across to fit, and the RHS "On this page" collapses (e.g. into a toggle/icon) rather than truncating. When width is ample, all three columns show.

Open question: can the browser/CSS reliably detect "not enough room" for the RHS panel given variable content widths and TOC depths?

Notes

• The lecture itself (prob_matrix.html) likely uses subsections more deeply than typical, which exposes the problem — but the theme behaviour is the underlying issue and will affect any long lecture with many sections.

Reproduction

1. Open https://python.quantecon.org/prob_matrix.html in a laptop-width browser at default font size
2. Look at the RHS "On this page" panel — count visible section links vs total sections in the page
3. Hover over the RHS panel and scroll — observe the main content scrolls instead of the panel

[mmcky]

• @mmcky to rework how testing is done. Building quantecon-book-theme-fixtuers so we can actually add these test cases as proper fixtures.

[DrDrij]

Thanks for highlighting @jstac, there's a deeper issue of checking theme functionality across different browser environmental specs.

@mmcky when a solution is found, suggest we run a few tests at the most common resolutions on Browserstack. Chrome responsive mode in the dev tools is ok for local testing, but not full environmental. Happy to take this on.
From GA4, source:

My thoughts:

1. Yep, right menu should scroll independently of the main content.
2. I would suggest that the right menu is no longer hovering on top of the page, but pushes the main content to the right when it opens (solve margin/white space issue). If the resolution is too small to fit the 3 menus, the right should be hidden.
3. Priority system sounds right to me. We should be able to detect the "not enough room" problem.

I'll try putting together a prototype so we can play with this idea.

[mmcky]

@DrDrij — quick info on what we currently test against, since PR #390 has just landed the migration to a fixtures-based Playwright setup.

Current Playwright viewport coverage

From playwright.config.ts:

Project	Viewport	UA
desktop-chrome	1280×720	Desktop Chrome
mobile-chrome	393×851 (Pixel 5 emulation)	Mobile Chrome

That's it — two fixed viewports, both Chromium-based, running on Ubuntu in CI. So the visual regression coverage you'd get from snapshot diffs in a theme PR is currently:

• Two viewport widths — doesn't surface bugs at e.g. 1920×1080 (most common desktop per your GA4), 1440×900, or 1024-ish tablet widths
• One browser engine — no Safari/WebKit, no Firefox/Gecko coverage
• No real device rendering — Pixel 5 emulation matches the viewport + UA but doesn't replicate actual mobile Safari quirks (iOS especially)

BrowserStack — agreed, good idea to document on QuantEcon/meta

Your GA4 screenshot above is exactly the right input for picking a target matrix. A few thoughts on how it could integrate:

• Cross-org infra concern — fits on QuantEcon/meta as a shared documentation page (BrowserStack auth, suggested matrix from GA4, how to invoke from CI). Multiple QuantEcon repos would benefit (lecture sites, this theme, sphinx-tojupyter, etc.), so centralizing the convention there avoids per-repo drift.
• Two ways it could plug in here: (a) on-demand smoke runs you trigger manually for a UX-impacting PR, or (b) a nightly/weekly cron that runs against the fixtures site and flags regressions. (a) is lower-cost; (b) catches drift over time without manual triggering.
• Playwright already supports BrowserStack via @browserstack/automate-cli — could be added as a parallel project in our config or a separate workflow that runs after the standard Chromium pass.

Where to find the new visual setup

After #390 merges:

• Fixtures repo: QuantEcon/quantecon-book-theme-fixtures
• Visual test docs: docs/developer/visual-testing.md
• prob_matrix.html (the page that motivated this issue) is now a permanent real-world fixture; header/sidebar snapshots are tracked, and the page renders against every theme PR's Netlify preview deploy for visual review.

Happy to help draft the BrowserStack doc on QuantEcon/meta when you're ready — let me know.

[mmcky]

Follow-up on the BrowserStack thread — opened a cross-org discussion on QuantEcon/meta for alignment beyond this repo: QuantEcon/meta#311.

The meta issue covers both:

1. Near-term Playwright expansion (free, low-effort) — adding WebKit, Firefox, and 3–4 more viewports/devices to the existing config. Covers most of what BrowserStack would for CSS / layout regressions, no external dependencies.
2. BrowserStack as a longer-term upgrade path — when real-device coverage is worth the cost (real iOS Safari, real Edge on Windows, OS-level font rendering), with a sequenced decision: do (1) first, see what gap remains, then decide.

@DrDrij — your GA4 screenshot is referenced there; the suggested sequence is "land Playwright expansion → 2 months of data → decide on BrowserStack with actual evidence of the gap." Happy to take #1 on in this repo once #390 lands.