From e8a3368226f0c38a905bf5040bd43cc2cc19671b Mon Sep 17 00:00:00 2001
From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Date: Fri, 28 Nov 2025 18:36:47 -0300
Subject: [PATCH] docs: Reduce layout shift when navigating between pages
 (#43758)

This is still not perfect, but it reduces the shift that happens when
navigating between pages that have and don't have the table of contents.
It also tries to reduce the theme flicker that happens by moving its
loading to an earlier moment.

Release Notes:

- N/A
---
 docs/theme/index.hbs    | 75 +++++++++++++++++++++--------------------
 docs/theme/page-toc.css | 12 +++++++
 docs/theme/page-toc.js  | 12 ++++++-
 3 files changed, 62 insertions(+), 37 deletions(-)
diff --git a/docs/theme/index.hbs b/docs/theme/index.hbs
index 8ac33ea0d7b2e3ae1730a3bc3e210a24466a0811..134fcacb38380d19e155f5f80c25bbb425a314b5 100644
--- a/docs/theme/index.hbs
+++ b/docs/theme/index.hbs
@@ -1,8 +1,22 @@
 <!DOCTYPE HTML>
-<html lang="{{ language }}" data-theme="{{ default_theme }}" data-color-scheme="{{ default_theme }}" dir="{{ text_direction }}">
+<html lang="{{ language }}" dir="{{ text_direction }}">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
+        <!-- Theme initialization - must run before any CSS loads to prevent flicker -->
+        <script>
+            (function() {
+                var theme;
+                try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+                if (theme === null || theme === undefined) {
+                    theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+                }
+                var html = document.documentElement;
+                html.setAttribute('data-theme', theme);
+                html.setAttribute('data-color-scheme', theme);
+                html.className = theme;
+            })();
+        </script>
         <title>{{ title }}</title>
         {{#if is_print }}
         <meta name="robots" content="noindex">
@@ -56,21 +70,9 @@
         <script>
             var path_to_root = "{{ path_to_root }}";
             var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "{{ preferred_dark_theme }}" : "{{ default_theme }}";
-        </script>
-
-        <!-- Support dark mode -->
-        <script>
-            var theme;
-            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
-            if (theme === null || theme === undefined) {
-                theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-            }
-            var html = document.querySelector('html');
-            html.classList.remove('light', 'dark')
-            html.classList.add(theme);
-            var body = document.querySelector('body');
-            body.classList.remove('no-js')
-            body.classList.add('js');
+            // Mark as JS-enabled
+            document.body.classList.remove('no-js');
+            document.body.classList.add('js');
         </script>
 
         <header class="header-bar">
@@ -298,10 +300,28 @@
                         </div>
                     </main>
                     <div class="toc-container">
-                        <nav class="pagetoc">
-                            <p class="toc-title">On this page</p>
-                        </nav>
+                        <nav class="pagetoc"></nav>
                     </div>
+                    <!-- Immediately detect if page has headins that are not h1 to prevent flicker -->
+                    <script>
+                        (function() {
+                            var tocContainer = document.querySelector('.toc-container');
+                            var headers = document.querySelectorAll('.header');
+                            var hasNonH1Headers = false;
+                            for (var i = 0; i < headers.length; i++) {
+                                var parent = headers[i].parentElement;
+                                if (parent && !parent.tagName.toLowerCase().startsWith('h1')) {
+                                    hasNonH1Headers = true;
+                                    break;
+                                }
+                            }
+                            if (hasNonH1Headers) {
+                                tocContainer.classList.add('has-toc');
+                            } else {
+                                tocContainer.classList.add('no-toc');
+                            }
+                        })();
+                    </script>
                 </div>
             </div>
         </div>
@@ -378,23 +398,6 @@
         {{/if}}
         {{/if}}
 
-        <script>
-          (function() {
-            var theme = localStorage.getItem('mdbook-theme');
-            var html = document.querySelector('html');
-            if (theme) {
-              html.setAttribute('data-theme', theme);
-              html.setAttribute('data-color-scheme', theme);
-              html.className = theme;
-            } else {
-              var systemPreference = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-              html.setAttribute('data-theme', systemPreference);
-              html.setAttribute('data-color-scheme', systemPreference);
-              html.className = systemPreference;
-            }
-          })();
-        </script>
-
         <!-- Amplitude Analytics -->
         <script>
           (function() {
diff --git a/docs/theme/page-toc.css b/docs/theme/page-toc.css
index ce9beea43c52b797a29a8c0df1dcf5f45ab1fd95..4ec21f986bb27f87679daeb2654721a0eeba2624 100644
--- a/docs/theme/page-toc.css
+++ b/docs/theme/page-toc.css
@@ -60,6 +60,18 @@
   color: var(--full-contrast);
 }
 
+.toc-container {
+  visibility: hidden;
+}
+
+.toc-container.has-toc {
+  visibility: visible;
+}
+
+.toc-container.no-toc {
+  display: none;
+}
+
 @media only screen and (max-width: 1020px) {
   .toc-container {
     display: none;
diff --git a/docs/theme/page-toc.js b/docs/theme/page-toc.js
index 02996772db2ec90c1484f94952ed2a76b1d094fd..5d1525025b8fbc6bbb00b21e22b446703e39ad9c 100644
--- a/docs/theme/page-toc.js
+++ b/docs/theme/page-toc.js
@@ -71,11 +71,21 @@ window.addEventListener("load", () => {
       sidetoc.style.display = "none";
     }
     if (tocContainer) {
-      tocContainer.style.display = "none";
+      tocContainer.classList.add("no-toc");
     }
     return;
   }
 
+  if (tocContainer) {
+    tocContainer.classList.add("has-toc");
+  }
+
+  const tocTitle = Object.assign(document.createElement("p"), {
+    className: "toc-title",
+    textContent: "On This Page",
+  });
+  pagetoc.appendChild(tocTitle);
+
   headers.forEach((header) => {
     const link = Object.assign(document.createElement("a"), {
       textContent: header.text,
