Fix deep-link anchor offset and improve layout stability in Firefox (#697)

Author: Claudio-Chies

.vitepress/theme/index.js

@@ -48,6 +48,27 @@ export default {
     };
     onMounted(() => {
       initZoom();
+      // Re-scroll to hash after fonts/layout settle. Firefox does not re-scroll
+      // after late layout shifts on huge pages (e.g. common.html), so the
+      // initial anchor jump lands far off. Run only on initial load.
+      if (inBrowser && location.hash) {
+        const id = decodeURIComponent(location.hash.slice(1));
+        const fontsReady = document.fonts?.ready ?? Promise.resolve();
+        const loadReady =
+          document.readyState === "complete"
+            ? Promise.resolve()
+            : new Promise((r) =>
+                window.addEventListener("load", r, { once: true })
+              );
+        Promise.all([fontsReady, loadReady]).then(() => {
+          requestAnimationFrame(() =>
+            requestAnimationFrame(() => {
+              const el = document.getElementById(id);
+              if (el) el.scrollIntoView();
+            })
+          );
+        });
+      }
     });
     watch(
       () => route.path,

.vitepress/theme/style.css

@@ -157,6 +157,15 @@
   display: inline; /* block by default set by vitepress */
 }
 
+/* Fix deep-link anchor offset under fixed navbar.
+   Also guards against Firefox layout-shift drift on huge pages (e.g. common.html). */
+html {
+  scroll-padding-top: calc(var(--vp-nav-height, 64px) + 16px);
+}
+:target {
+  scroll-margin-top: calc(var(--vp-nav-height, 64px) + 16px);
+}
+
 /* Make content area a little wider to improve tables */
 .content-container {
   max-width: 100% !important;