Make sidebar scrollable and sticky (on modern browsers) (#91)

dlukes · web-flow · commit 0d781e45bc33 · 2022-01-11T10:27:31.000+01:00
Just make the sidebar stick to the top with CSS and show a scrollbar on
overflow. There's no fallback for older browsers -- since up to now,
this didn't work for anyone (because "intelligent" scrolling has been
broken for years), I assume improving the UX at least for modern
browsers is still a net improvement.
diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css
@@ -51,7 +51,15 @@ form.inline-search input[type="submit"] {
     width: 40px;
 }
 
+div.document {
+    display: flex;
+}
+
 div.sphinxsidebar {
+    float: none;
+    position: sticky;
+    top: 0;
+    max-height: 100vh;
     background-color: #eeeeee;
     border-radius: 5px;
     line-height: 130%;
@@ -62,6 +70,13 @@ div.sphinxsidebar h3, div.sphinxsidebar h4 {
     margin-top: 1.5em;
 }
 
+div.sphinxsidebarwrapper {
+    box-sizing: border-box;
+    height: 100%;
+    overflow-x: hidden;
+    overflow-y: auto;
+}
+
 div.sphinxsidebarwrapper > h3:first-child {
     margin-top: 0.2em;
 }
diff --git a/python_docs_theme/static/sidebar.js b/python_docs_theme/static/sidebar.js
@@ -2,8 +2,8 @@
  * sidebar.js
  * ~~~~~~~~~~
  *
- * This script makes the Sphinx sidebar collapsible and implements intelligent
- * scrolling. This is a slightly modified version of Sphinx's own sidebar.js.
+ * This script makes the Sphinx sidebar collapsible. This is a slightly
+ * modified version of Sphinx's own sidebar.js.
  *
  * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds in
  * .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton used to
@@ -25,10 +25,7 @@ $(function() {
   // global elements used by the functions.
   // the 'sidebarbutton' element is defined as global after its
   // creation, in the add_sidebar_button function
-  var jwindow = $(window);
-  var jdocument = $(document);
   var bodywrapper = $('.bodywrapper');
-  var documentwrapper = $('.documentwrapper');
   var sidebar = $('.sphinxsidebar');
   var sidebarwrapper = $('.sphinxsidebarwrapper');
 
@@ -46,13 +43,6 @@ $(function() {
   var dark_color = '#AAAAAA';
   var light_color = '#CCCCCC';
 
-  function get_viewport_height() {
-    if (window.innerHeight)
-      return window.innerHeight;
-    else
-      return jwindow.height();
-  }
-
   function sidebar_is_collapsed() {
     return sidebarwrapper.is(':not(:visible)');
   }
@@ -62,8 +52,6 @@ $(function() {
       expand_sidebar();
     else
       collapse_sidebar();
-    // adjust the scrolling of the sidebar
-    scroll_sidebar();
   }
 
   function collapse_sidebar() {
@@ -72,7 +60,6 @@ $(function() {
     bodywrapper.css('margin-left', bw_margin_collapsed);
     sidebarbutton.css({
         'margin-left': '0',
-        'height': documentwrapper.height(),
         'border-radius': '5px'
     });
     sidebarbutton.find('span').text('»');
@@ -86,35 +73,28 @@ $(function() {
     sidebarwrapper.show();
     sidebarbutton.css({
         'margin-left': ssb_width_expanded-12,
-        'height': Math.max(sidebarwrapper.height(), documentwrapper.height()),
         'border-radius': '0 5px 5px 0'
     });
     sidebarbutton.find('span').text('«');
     sidebarbutton.attr('title', _('Collapse sidebar'));
-    //sidebarwrapper.css({'padding-top':
-    //  Math.max(window.pageYOffset - sidebarwrapper.offset().top, 10)});
     document.cookie = 'sidebar=expanded';
   }
 
   function add_sidebar_button() {
     sidebarwrapper.css({
         'float': 'left',
         'margin-right': '0',
-        'width': ssb_width_expanded - 28
+        'width': ssb_width_expanded - 13
     });
     // create the button
     sidebar.append(
       '<div id="sidebarbutton"><span>&laquo;</span></div>'
     );
     var sidebarbutton = $('#sidebarbutton');
-    // find the height of the viewport to center the '<<' in the page
-    var viewport_height = get_viewport_height();
-    var sidebar_offset = sidebar.offset().top;
-    var sidebar_height = Math.max(documentwrapper.height(), sidebar.height());
     sidebarbutton.find('span').css({
         'display': 'block',
         'position': 'fixed',
-        'top': Math.min(viewport_height/2, sidebar_height/2 + sidebar_offset) - 10
+        'top': '50%'
     });
 
     sidebarbutton.click(toggle_sidebar);
@@ -125,8 +105,7 @@ $(function() {
         'background-color': '#CCCCCC',
         'font-size': '1.2em',
         'cursor': 'pointer',
-        'height': sidebar_height,
-        'padding-top': '1px',
+        'height': '100%',
         'padding-left': '1px',
         'margin-left': ssb_width_expanded - 12
     });
@@ -161,34 +140,4 @@ $(function() {
   add_sidebar_button();
   var sidebarbutton = $('#sidebarbutton');
   set_position_from_cookie();
-
-
-  /* intelligent scrolling */
-  function scroll_sidebar() {
-    var sidebar_height = sidebarwrapper.height();
-    var viewport_height = get_viewport_height();
-    var offset = sidebar.position()['top'];
-    var wintop = jwindow.scrollTop();
-    var winbot = wintop + viewport_height;
-    var curtop = sidebarwrapper.position()['top'];
-    var curbot = curtop + sidebar_height;
-    // does sidebar fit in window?
-    if (sidebar_height < viewport_height) {
-      // yes: easy case -- always keep at the top
-      sidebarwrapper.css('top', $u.min([$u.max([0, wintop - offset - 10]),
-                            jdocument.height() - sidebar_height - 200]));
-    }
-    else {
-      // no: only scroll if top/bottom edge of sidebar is at
-      // top/bottom edge of window
-      if (curtop > wintop && curbot > winbot) {
-        sidebarwrapper.css('top', $u.max([wintop - offset - 10, 0]));
-      }
-      else if (curtop < wintop && curbot < winbot) {
-        sidebarwrapper.css('top', $u.min([winbot - sidebar_height - offset - 20,
-                              jdocument.height() - sidebar_height - 200]));
-      }
-    }
-  }
-  jwindow.scroll(scroll_sidebar);
 });
