[TASK] Improve scrolling behavior & fix header position (#927)

Ensured scrolling to main sections moves to the top of the page.
Adjusted anchor scrolling so subsections are positioned correctly.
Fixed the header to the top while scrolling.
Added scroll-margin-top to prevent content from being hidden under the
header.

Resolves #845
Resolves #843

Author: linawolf

packages/typo3-docs-theme/assets/js/scrolling.js

@@ -0,0 +1,51 @@
+document.addEventListener("DOMContentLoaded", function () {
+  function adjustScrollMargin() {
+    const header = document.querySelector("header");
+    const headerHeight = header ? header.offsetHeight : 80; // Default fallback
+
+    document.querySelectorAll(".section").forEach(section => {
+      section.style.scrollMarginTop = `${headerHeight + 10}px`; // Extra space for visibility
+    });
+  }
+
+  function scrollToAnchor() {
+    const hash = window.location.hash.substring(1); // Get anchor without #
+    if (!hash) return;
+
+    const target = document.getElementById(hash);
+    if (target) {
+      // Check if the target is the first main section (h1)
+      const isFirstSection = target.closest(".section")?.querySelector("h1") !== null;
+
+      if (isFirstSection) {
+        window.scrollTo({
+          top: 0,
+          behavior: "smooth"
+        });
+      } else {
+        setTimeout(() => {
+          target.scrollIntoView({ behavior: "smooth", block: "start" });
+        }, 50); // Delay ensures styles apply
+      }
+    }
+  }
+
+  // Adjust scroll margin on load
+  adjustScrollMargin();
+
+  // Handle initial anchor scrolling
+  setTimeout(scrollToAnchor, 100); // Slight delay for rendering
+
+  // Handle clicks on internal links
+  document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+    anchor.addEventListener("click", function (e) {
+      e.preventDefault();
+      const targetId = this.getAttribute("href").substring(1);
+      history.pushState(null, null, `#${targetId}`); // Update URL without reload
+      scrollToAnchor();
+    });
+  });
+
+  // Adjust when resizing (e.g., switching between desktop & mobile)
+  window.addEventListener("resize", adjustScrollMargin);
+});

packages/typo3-docs-theme/assets/sass/layout/_header.scss

@@ -0,0 +1,11 @@
+header {
+    position: sticky;
+    top: 0;
+    width: 100%;
+    z-index: 1000; /* Ensures it's above other content */
+    background-color: white; /* Adjust as needed */
+}
+
+.section {
+    scroll-margin-top: 114px; /* Adjust to match the header height */
+}

packages/typo3-docs-theme/assets/sass/theme.scss

@@ -64,6 +64,7 @@
 
 // Page structure
 @import 'layout/breadcrumb';
+@import 'layout/header';
 @import 'layout/footer';
 @import 'layout/logo';
 @import 'layout/navigation/main_navigation';

packages/typo3-docs-theme/resources/public/css/theme.css

@@ -25853,6 +25853,18 @@ dl.field-list > dt:after {
   }
 }
 
+header {
+  position: sticky;
+  top: 0;
+  width: 100%;
+  z-index: 1000; /* Ensures it's above other content */
+  background-color: white; /* Adjust as needed */
+}
+
+.section {
+  scroll-margin-top: 114px; /* Adjust to match the header height */
+}
+
 @media (min-width: 768px) {
   .footer-main {
     margin: calc(40px / 2 * -1);