👌 IMPROVE: RHS TOC sticky when scrolling option #144

DrDrij · 2021-06-06T01:01:54Z

Fixes #133

Add config option to make the in-page-TOC in the right column sticky (stays in view when scrolling)
Highlight respective TOC items when scrolling

The page TOC will now highlight as the user scrolls.

A config option is required to activate the sticky feature and highlighting functionality. This defaults to False where the page TOC is not sticky.

sphinx:
  config:
    html_theme_options:
      sticky_contents: true

Screen.Recording.2021-06-22.at.4.04.08.pm.mov

mmcky · 2021-06-06T09:38:41Z

nice work @DrDrij -- it would be good to get the preview building with the updated RHS toc. Is that possible?

codecov · 2021-06-11T01:35:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.12%. Comparing base (976718a) to head (a75930f).
⚠️ Report is 71 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #144   +/-   ##
=======================================
  Coverage   71.12%   71.12%           
=======================================
  Files           2        2           
  Lines         239      239           
=======================================
  Hits          170      170           
  Misses         69       69

Flag	Coverage Δ
pytests	`71.12% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

mmcky · 2021-06-18T03:06:22Z

@DrDrij is the outstanding checkbox still in work?

mmcky · 2021-06-22T06:27:01Z

re: option name perhaps we need to specify rhs perhaps.

The main toc is persistent_toc: true

So perhaps we need to differentiate these toc objects a bit more clearly. Maybe LHS == TOC and RHS == CONTENTS

mmcky · 2021-07-20T02:38:21Z

@DrDrij what do you think re: comments / names?

mmcky · 2021-09-07T04:33:09Z

@DrDrij do you think you would have some time in the next two weeks to see if we can close this?

DrDrij · 2021-09-09T04:20:29Z

@mmcky Great idea. Changed the parameter to sticky_contents: true from sticky_toc: true.
Shall I create a PR on the myst sites to add the parameter? programming, python, advanced, datascience, julia? I suppose we only need to add it if we want sticky as true (default false).

I think that covers it for this PR :)

mmcky · 2023-05-03T05:55:13Z

@AakashGfude the latest netlify doesn't seem to show the "sticky" rhs toc?

mmcky · 2023-05-04T00:40:37Z

@AakashGfude let's revert 0acf72c and I will update the quantecon-book-theme branch on lecture-python-programming.

https://github.com/QuantEcon/lecture-python-programming.myst

mmcky · 2023-05-04T00:45:27Z

@AakashGfude I just pushed c8fd78a

mmcky · 2023-05-04T00:46:11Z

@AakashGfude once you get the tests and merge conflict sorted -- then please ping me for review. Thanks.

mmcky · 2023-05-05T02:00:03Z

@AakashGfude this looks sticky now 👍

What do you think? I suspect @jstac will prefer the non-sticky version but it is nice that our theme can support this option.

mmcky · 2023-05-05T02:01:19Z

@jstac this PR enables the RHS within page contents to stay visible in the margin

https://64546294cce6883938fb185c--hungry-lovelace-7d0512.netlify.app/python_by_example.html

Let me know your thoughts on this? I am in two minds - I like the clean view of it just being at the top (i.e. not sticky) but it can be handy to navigated within the page with it available all the time.

AakashGfude · 2023-05-05T15:48:28Z

Thanks @mmcky. This looks good now. Yes, I think by default we should keep it non-sticky. Good to have the option.

Copilot

Pull Request Overview

This PR implements a sticky right-hand side (RHS) table of contents (TOC) feature with scroll-based highlighting for the QuantEcon Book Theme. The feature is configurable through a new theme option and defaults to disabled to maintain backward compatibility.

Key changes include:

Added a new configuration option sticky_contents that defaults to False
Implemented CSS positioning to make the TOC sticky when the option is enabled
Added JavaScript scroll spy functionality to highlight current section in TOC
Removed an existing CSS rule that was interfering with the new navigation behavior

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/scss/quantecon-book-theme.scss	Added CSS for sticky positioning and active state styling for TOC items
src/js/quantecon-book-theme.js	Added ScrollSpy plugin and initialization for TOC highlighting
src/jinja/theme.conf.j2	Added sticky_contents configuration option with default False
src/jinja/theme.conf	Added sticky_contents configuration option
quantecon_book_theme/theme.conf	Updated compiled theme configuration and stylesheet reference
quantecon_book_theme/static/*.css	Compiled CSS assets with new sticky TOC styles
quantecon_book_theme/static/*.js	Compiled JavaScript with ScrollSpy functionality
quantecon_book_theme/layout.html	Added conditional sticky class based on theme configuration
.pre-commit-config.yaml	Added MarkupSafe dependency pin for compatibility
.github/workflows/ci.yml	Updated Python version from 3.9 to 3.10

_{You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.}

Copilot · 2025-08-16T00:38:46Z

src/scss/quantecon-book-theme.scss

+
+          &.active {
+            >a {
+              //color: $color-primary;


Remove the commented out color property. Commented code should be cleaned up rather than left in the codebase.

Suggested change

//color: $color-primary;

Copilot · 2025-08-16T00:38:46Z

src/scss/quantecon-book-theme.scss


    .nav>.active>ul {
-      display: block;
+      // display: block;


Remove the commented out display property. If this rule needs to be disabled, consider removing it entirely or documenting why it's commented out.

Suggested change

// display: block;

Copilot · 2025-08-16T00:38:46Z

src/scss/quantecon-book-theme.scss


+.toctree-checkbox[type="checkbox"] {
+  position: absolute;
+  left: 400rem;


The value 400rem is a magic number that appears to be used to hide elements off-screen. Consider using a more semantic approach like left: -9999px or display: none with proper accessibility considerations.

Suggested change

left: 400rem;

left: -9999px;

Copilot · 2025-08-16T00:38:47Z

src/js/quantecon-book-theme.js

@@ -1,3 +1,6 @@
+// ScrollSpy Plugin: https://github.com/r3plica/Scrollspy
+!function($,window,document,undefined){$.fn.extend({scrollspy:function(options){var defaults={namespace:"scrollspy",activeClass:"active",animate:!1,duration:1e3,offset:0,container:window,replaceState:!1};options=$.extend({},defaults,options);var add=function(ex1,ex2){return parseInt(ex1,10)+parseInt(ex2,10)},findElements=function(links){for(var elements=[],i=0;i<links.length;i++){var link=links[i],hash=$(link).attr("href"),element=$(hash);if(element.length>0){var top=Math.floor(element.offset().top),bottom=top+Math.floor(element.outerHeight());elements.push({element:element,hash:hash,top:top,bottom:bottom})}}return elements},findLink=function(links,hash){for(var i=0;i<links.length;i++){var link=$(links[i]);if(link.attr("href")===hash)return link}},resetClasses=function(links){for(var i=0;i<links.length;i++)$(links[i]).parent().removeClass(options.activeClass)},scrollArea="";return this.each(function(){for(var element=this,container=$(options.container),links=$(element).find("a"),i=0;i<links.length;i++){var link=links[i];$(link).on("click",function(e){var target=$(this).attr("href"),$target=$(target);if($target.length>0){var top=add($target.offset().top,options.offset);options.animate?$("html, body").animate({scrollTop:top},options.duration):window.scrollTo(0,top),e.preventDefault()}})}resetClasses(links);var elements=findElements(links),trackChanged=function(){for(var link,position={top:add($(this).scrollTop(),Math.abs(options.offset)),left:$(this).scrollLeft()},i=0;i<elements.length;i++){var current=elements[i];if(position.top>=current.top&&position.top<current.bottom){var hash=current.hash;if(link=findLink(links,hash)){options.onChange&&scrollArea!==hash&&(options.onChange(current.element,$(element),position),scrollArea=hash),options.replaceState&&history.replaceState({},"","/"+hash),resetClasses(links),link.parent().addClass(options.activeClass);break}}}!link&&"exit"!==scrollArea&&options.onExit&&(options.onExit($(element),position),resetClasses(links),scrollArea="exit",options.replaceState&&history.replaceState({},"","/"))};container.bind("scroll."+options.namespace,function(){trackChanged()}),$(document).ready(function(e){trackChanged()})})}})}(jQuery,window,document);


The ScrollSpy plugin is minified/obfuscated code that makes debugging and maintenance difficult. Consider using a readable version during development or include a reference to the original source for better maintainability.

Copilot · 2025-08-16T00:38:47Z

src/js/quantecon-book-theme.js

-});
+    // Highlight page TOC links as user scrolls
+    $(".sticky #bd-toc-nav ul").scrollspy();
+


The selector .sticky #bd-toc-nav ul assumes a specific DOM structure. Consider making this more robust by checking if the element exists before initializing scrollspy to avoid potential errors.

Suggested change

var $tocNav = $(".sticky #bd-toc-nav ul");

if ($tocNav.length > 0) {

$tocNav.scrollspy();

}

mmcky · 2025-08-16T00:42:13Z

@DrDrij would you mind reviewing this PR. Not sure why we didn't merge this when it was ready. I still think it would be a nice feature to have.

mmcky · 2025-08-16T00:43:11Z

@copilot are you able to review this PR and resolve the merge conflicts?

mmcky · 2025-08-16T00:44:00Z

@DrDrij clearly a lot has changed. It might be easier to open a new PR with the final changes?

mmcky · 2025-08-25T01:13:22Z

@copilot are you able to review this PR and update it to the most recent main branch fixing merge conflicts?

mmcky · 2025-09-23T02:22:30Z

Closing in favour of #316

Add condition for sticky toc

499b061

DrDrij requested review from AakashGfude and mmcky June 6, 2021 01:01

github-actions bot temporarily deployed to commit June 6, 2021 01:03 Inactive

Merge branch 'master' into rhs-toc-adjustments

7923265

github-actions bot temporarily deployed to commit June 11, 2021 01:40 Inactive

mmcky marked this pull request as draft June 21, 2021 06:09

Add link highlighting function for page TOC

2e6acdd

github-actions bot temporarily deployed to commit June 22, 2021 05:32 Inactive

DrDrij added 3 commits June 22, 2021 15:39

Add styles for page TOC highlighting

0fe9120

Page TOC style tweak

6f9d006

Hide nested pages in page TOC

0b98935

github-actions bot temporarily deployed to commit June 22, 2021 05:52 Inactive

DrDrij added 2 commits June 22, 2021 15:57

Add sticky_toc option to conf

17ccb9e

Only highlight if sticky

85ed2f2

github-actions bot temporarily deployed to commit June 22, 2021 06:08 Inactive

DrDrij mentioned this pull request Jun 22, 2021

[TEST] quantecon-book-theme@rhs-toc-adjustments QuantEcon/lecture-python.myst#156

Closed

DrDrij added 4 commits September 9, 2021 14:13

Add context to RHS TOC parameter

341ee62

Add context to RHS TOC parameter

d5e85ab

Add context to RHS TOC parameter

8fe2483

Add context to RHS TOC parameter

7f004f0

github-actions bot temporarily deployed to commit September 9, 2021 04:19 Inactive

github-actions bot temporarily deployed to commit September 9, 2021 04:20 Inactive

github-actions bot temporarily deployed to commit May 1, 2023 09:14 Inactive

AakashGfude added 2 commits May 3, 2023 17:12

keeping it True by deafult

0acf72c

resolved merge conflict

9abf43c

github-actions bot temporarily deployed to commit May 3, 2023 07:22 Inactive

AakashGfude and others added 4 commits May 4, 2023 12:14

sticky_contents default reverted

8416d73

Merge branch 'master' into rhs-toc-adjustments

6f47f6a

running pre-commit

06127b2

update to python=3.10

a75930f

github-actions bot temporarily deployed to commit May 5, 2023 01:57 Inactive

mmcky added the on-hold label Aug 8, 2023

mmcky requested a review from Copilot August 16, 2025 00:37

mmcky removed the on-hold label Aug 16, 2025

Copilot AI reviewed Aug 16, 2025

View reviewed changes

mmcky assigned Copilot Aug 16, 2025

mmcky mentioned this pull request Sep 23, 2025

ENH: update PR to implement enhancement #315

Open

Copilot AI mentioned this pull request Sep 23, 2025

ENH: Implement sticky RHS table of contents with scroll highlighting #316

Closed

mmcky closed this Sep 23, 2025

mmcky deleted the rhs-toc-adjustments branch September 23, 2025 02:22

		@@ -1,3 +1,6 @@
		// ScrollSpy Plugin: https://github.com/r3plica/Scrollspy
		!function($,window,document,undefined){$.fn.extend({scrollspy:function(options){var defaults={namespace:"scrollspy",activeClass:"active",animate:!1,duration:1e3,offset:0,container:window,replaceState:!1};options=$.extend({},defaults,options);var add=function(ex1,ex2){return parseInt(ex1,10)+parseInt(ex2,10)},findElements=function(links){for(var elements=[],i=0;i<links.length;i++){var link=links[i],hash=$(link).attr("href"),element=$(hash);if(element.length>0){var top=Math.floor(element.offset().top),bottom=top+Math.floor(element.outerHeight());elements.push({element:element,hash:hash,top:top,bottom:bottom})}}return elements},findLink=function(links,hash){for(var i=0;i<links.length;i++){var link=$(links[i]);if(link.attr("href")===hash)return link}},resetClasses=function(links){for(var i=0;i<links.length;i++)$(links[i]).parent().removeClass(options.activeClass)},scrollArea="";return this.each(function(){for(var element=this,container=$(options.container),links=$(element).find("a"),i=0;i<links.length;i++){var link=links[i];$(link).on("click",function(e){var target=$(this).attr("href"),$target=$(target);if($target.length>0){var top=add($target.offset().top,options.offset);options.animate?$("html, body").animate({scrollTop:top},options.duration):window.scrollTo(0,top),e.preventDefault()}})}resetClasses(links);var elements=findElements(links),trackChanged=function(){for(var link,position={top:add($(this).scrollTop(),Math.abs(options.offset)),left:$(this).scrollLeft()},i=0;i<elements.length;i++){var current=elements[i];if(position.top>=current.top&&position.top<current.bottom){var hash=current.hash;if(link=findLink(links,hash)){options.onChange&&scrollArea!==hash&&(options.onChange(current.element,$(element),position),scrollArea=hash),options.replaceState&&history.replaceState({},"","/"+hash),resetClasses(links),link.parent().addClass(options.activeClass);break}}}!link&&"exit"!==scrollArea&&options.onExit&&(options.onExit($(element),position),resetClasses(links),scrollArea="exit",options.replaceState&&history.replaceState({},"","/"))};container.bind("scroll."+options.namespace,function(){trackChanged()}),$(document).ready(function(e){trackChanged()})})}})}(jQuery,window,document);

+    var $tocNav = $(".sticky #bd-toc-nav ul");
+    if ($tocNav.length > 0) {
+        $tocNav.scrollspy();
+    }

Uh oh!

👌 IMPROVE: RHS TOC sticky when scrolling option #144

👌 IMPROVE: RHS TOC sticky when scrolling option #144

Uh oh!

Conversation

DrDrij commented Jun 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmcky commented Jun 6, 2021

Uh oh!

codecov bot commented Jun 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mmcky commented Jun 18, 2021

Uh oh!

mmcky commented Jun 22, 2021

Uh oh!

mmcky commented Jul 20, 2021

Uh oh!

mmcky commented Sep 7, 2021

Uh oh!

DrDrij commented Sep 9, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmcky commented May 3, 2023

Uh oh!

mmcky commented May 4, 2023

Uh oh!

mmcky commented May 4, 2023

Uh oh!

mmcky commented May 4, 2023

Uh oh!

mmcky commented May 5, 2023

Uh oh!

mmcky commented May 5, 2023

Uh oh!

AakashGfude commented May 5, 2023

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

mmcky commented Aug 16, 2025

Uh oh!

mmcky commented Aug 16, 2025

Uh oh!

mmcky commented Aug 16, 2025

Uh oh!

mmcky commented Aug 25, 2025

Uh oh!

mmcky commented Sep 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DrDrij commented Jun 6, 2021 •

edited

Loading

codecov bot commented Jun 11, 2021 •

edited

Loading

DrDrij commented Sep 9, 2021 •

edited

Loading