[HTML Theme]: Add "Navigate to Top" Button

sphinx/themes/basic/layout.html

@@ -114,6 +114,9 @@ <h3>{{ _('Navigation') }}</h3>
     {%- if not embedded %}
     {%- block scripts %}
     {{- script() }}
+    {%- block navigate_to_top_script %}
+    <script src="{{ pathto('_static/navigate_top.js', 1) }}"></script>
+    {%- endblock %}
     {%- endblock %}
     {%- if pageurl %}
     <link rel="canonical" href="{{ pageurl|e }}" />
@@ -213,5 +216,12 @@ <h3>{{ _('Navigation') }}</h3>
     {%- endif %}
     </div>
 {%- endblock %}
+
+{%- block navigate_to_top %}
+<a href="#" id="navigate-to-top" class="hide-navigate-to-top">
+  <button>Navigate to Top</button>
+</a>
+{%- endblock %}
+
   </body>
 </html>

sphinx/themes/basic/static/basic.css.jinja

@@ -11,6 +11,10 @@
 
 /* -- main layout ----------------------------------------------------------- */
 
+html {
+    scroll-behavior: smooth;
+}
+
 div.clearer {
     clear: both;
 }
@@ -112,6 +116,23 @@ img {
     max-width: 100%;
 }
 
+/* -- navigate to top -------------------------------------------------------*/
+#navigate-to-top {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 1000;
+}
+
+.hide-navigate-to-top {
+    display: none;
+}
+
+.show-navigate-to-top {
+    display: block;
+}
+
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {

sphinx/themes/basic/static/navigate_top.js

@@ -0,0 +1,56 @@
+/* Add Navigate to Top Functionality */
+// inspired from https://github.com/pradyunsg/furo
+
+"use strict";
+
+// fetch the pixels scrolled vertically from origin
+var lastScrollTop = document.documentElement.scrollTop;
+const GO_TO_TOP_OFFSET = 64;
+
+const _scrollToTop = (positionY) => {
+    const navigateToTopButtom = document.getElementById("navigate-to-top");
+    // position not yet crossed of offset
+    if (positionY < GO_TO_TOP_OFFSET) {
+        navigateToTopButtom.classList.add("hide-navigate-to-top");
+        navigateToTopButtom.classList.remove("show-navigate-to-top");
+    } else {
+        if (positionY > lastScrollTop) {
+            // scrolling down
+            navigateToTopButtom.classList.add("hide-navigate-to-top");
+            navigateToTopButtom.classList.remove("show-navigate-to-top");
+        } else if (positionY < lastScrollTop) {
+            // scrolling up
+            navigateToTopButtom.classList.add("show-navigate-to-top");
+            navigateToTopButtom.classList.remove("hide-navigate-to-top");
+        }
+    }
+    // update the position for next scroll event
+    lastScrollTop = positionY;
+};
+
+const _setupScrollHandler = () => {
+    let lastKnownScrollPosition = 0;
+    // help to keep track if requestAnimationFrame is scheduled
+    let ticking = false;
+
+    document.addEventListener("scroll", (event) => {
+        lastKnownScrollPosition = window.scrollY;
+
+        if (!ticking) {
+            window.requestAnimationFrame(() => {
+                _scrollToTop(lastKnownScrollPosition)
+                // animation is complete (so now be called again)
+                ticking = false;
+            });
+
+            // it's scheduled so don't call back the requestAnimationFrame
+            ticking = true;
+        }
+    });
+};
+
+const _main = () => {
+    _setupScrollHandler();
+};
+
+document.addEventListener("DOMContentLoaded", _main);