From 1224c70c0c9dce487c9b25605fc7f6ef61fcaaa8 Mon Sep 17 00:00:00 2001
From: Lars Francke <git@lars-francke.de>
Date: Tue, 28 Jul 2026 17:04:50 +0200
Subject: [PATCH 1/2] perf: Load the search UI on first use and make result
 cards one link

The pagefind js and css were the last render-blocking requests in the
head of every page; they now load when the search popover first opens
(button, Ctrl+K), keeping search behaviour identical from the second
keystroke of a visit onwards.

The result template used to wrap only the title in a link while
pagefind's stylesheet gave the whole card a pointer cursor; the card
is one block-level link now, with hover and focus-visible styling, and
the keyboard navigation follows the flatter markup.
---
 ui/src/css/search.css              |  18 +++++
 ui/src/js/07-search.js             |  24 ++++---
 ui/src/partials/footer-scripts.hbs | 105 ++++++++++++++++-------------
 ui/src/partials/head-scripts.hbs   |   1 -
 ui/src/partials/head-styles.hbs    |   1 -
 5 files changed, 92 insertions(+), 57 deletions(-)

diff --git a/ui/src/css/search.css b/ui/src/css/search.css
index fe4a37892..0ac3d55e6 100644
--- a/ui/src/css/search.css
+++ b/ui/src/css/search.css
@@ -48,6 +48,24 @@
   margin-top: 0;
 }
 
+/* the whole result card is one link */
+a.pagefind-modular-list-inner {
+  display: block;
+  text-decoration: none;
+}
+
+a.pagefind-modular-list-inner:hover,
+a.pagefind-modular-list-inner:focus-visible {
+  background-color: var(--color-background2);
+  outline-offset: 2px;
+}
+
+.pagefind-modular-list-title {
+  color: var(--color-brand-primary);
+  font-weight: 600;
+  margin: 0;
+}
+
 .pagefind-modular-list-breadcrumbs {
   font-size: calc(18px * var(--pagefind-ui-scale));
   font-weight: 500;
diff --git a/ui/src/js/07-search.js b/ui/src/js/07-search.js
index 209d84f05..1e79b397b 100644
--- a/ui/src/js/07-search.js
+++ b/ui/src/js/07-search.js
@@ -5,10 +5,13 @@
     document.getElementById('search-background').style.display = 'block'
     document.getElementById('search').style.display = 'block'
 
-    // focus the textbox after popover appears
-    focusSearchInput()
-    // add eventlisteners after popover appears
-    addNavigationToSearch()
+    // the search assets load on first use (see footer-scripts.hbs)
+    window.loadSearch().then(function () {
+      // focus the textbox after the input exists
+      focusSearchInput()
+      // add eventlisteners after popover appears
+      addNavigationToSearch()
+    })
   }
 
   function closeSearchPopover () {
@@ -37,19 +40,20 @@
   }
 
   function addNavigationInSearchResults (event) {
+    // the focused element is the result card link, a direct child of the li
     if (event.key === 'ArrowDown' && document.activeElement.classList.contains('pagefind-modular-list-link')) {
       event.preventDefault() // prevent page scrolling
-      var nextSibling = document.activeElement.parentElement.parentElement.parentElement.nextElementSibling
-      if (nextSibling) {
-        nextSibling.querySelector('a').focus()
+      var nextResult = document.activeElement.closest('li').nextElementSibling
+      if (nextResult) {
+        nextResult.querySelector('a').focus()
       }
     }
 
     if (event.key === 'ArrowUp' && document.activeElement.classList.contains('pagefind-modular-list-link')) {
       event.preventDefault() // prevent page scrolling
-      var previousSibling = document.activeElement.parentElement.parentElement.parentElement.previousElementSibling
-      if (previousSibling) {
-        previousSibling.querySelector('a').focus()
+      var previousResult = document.activeElement.closest('li').previousElementSibling
+      if (previousResult) {
+        previousResult.querySelector('a').focus()
       }
     }
   }
diff --git a/ui/src/partials/footer-scripts.hbs b/ui/src/partials/footer-scripts.hbs
index 56ef71d6d..b22e1a3c9 100644
--- a/ui/src/partials/footer-scripts.hbs
+++ b/ui/src/partials/footer-scripts.hbs
@@ -2,57 +2,72 @@
 <script async src="{{{uiRootPath}}}/js/vendor/highlight.js"></script>
 <script async src="{{{uiRootPath}}}/js/vendor/tabs.js" data-sync-storage-key="preferred-tab"></script>
 <script>
-    // This script block loads the pagefind search UI.
+    // Loads the pagefind search UI on first use (see 07-search.js); the
+    // assets stay off the critical rendering path of every page.
     // Some styling is customized, these classes are found in search.css.
-    window.addEventListener('DOMContentLoaded', (event) => {
-        const instance = new PagefindModularUI.Instance({
-            // customized rank tuning - see https://pagefind.app/docs/ranking/
-            ranking: {
-                termSaturation: 0.4,
-                termSimilarity: 10.0
-            }});
-        instance.add(new PagefindModularUI.Input({
-            containerElement: "#search-input"
-        }));
-        instance.add(new PagefindModularUI.ResultList({
-            containerElement: "#search-results",
-            resultTemplate: (result) => {
-                const el = document.createElement("li");
-                el.classList.add("pagefind-modular-list-result");
+    window.loadSearch = (function () {
+        let ready
 
-                const innerEl = document.createElement("div");
-                innerEl.classList.add("pagefind-modular-list-inner");
-                el.appendChild(innerEl);
+        function initSearch () {
+            const instance = new PagefindModularUI.Instance({
+                // customized rank tuning - see https://pagefind.app/docs/ranking/
+                ranking: {
+                    termSaturation: 0.4,
+                    termSimilarity: 10.0
+                }});
+            instance.add(new PagefindModularUI.Input({
+                containerElement: "#search-input"
+            }));
+            instance.add(new PagefindModularUI.ResultList({
+                containerElement: "#search-results",
+                resultTemplate: (result) => {
+                    const el = document.createElement("li");
+                    el.classList.add("pagefind-modular-list-result");
 
-                // Create the child element for the breadcrumbs
-                const bcEl = document.createElement("p");
-                bcEl.classList.add("pagefind-modular-list-breadcrumbs");
-                parts = (result.meta.breadcrumbs ?? '').split('.').map(part => part.trim()).filter(part => part.length > 0);
-                parts.shift();
-                parts.pop();
-                bcEl.innerText = parts.join(' / ');
-                innerEl.appendChild(bcEl);
+                    // the whole result card is one link
+                    const linkEl = document.createElement("a");
+                    linkEl.classList.add("pagefind-modular-list-link", "pagefind-modular-list-inner");
+                    linkEl.href = result.url;
+                    el.appendChild(linkEl);
 
-                // Create the child element for the title
-                const titleEl = document.createElement("p");
-                titleEl.classList.add("pagefind-modular-list-title");
-                innerEl.appendChild(titleEl);
+                    const bcEl = document.createElement("p");
+                    bcEl.classList.add("pagefind-modular-list-breadcrumbs");
+                    const parts = (result.meta.breadcrumbs ?? '').split('.').map(part => part.trim()).filter(part => part.length > 0);
+                    parts.shift();
+                    parts.pop();
+                    bcEl.innerText = parts.join(' / ');
+                    linkEl.appendChild(bcEl);
 
-                // Create the anchor element
-                const linkEl = document.createElement("a");
-                linkEl.classList.add("pagefind-modular-list-link");
-                linkEl.href = result.url;
-                linkEl.innerText = result.meta.title;
-                titleEl.appendChild(linkEl);
+                    const titleEl = document.createElement("p");
+                    titleEl.classList.add("pagefind-modular-list-title");
+                    titleEl.innerText = result.meta.title;
+                    linkEl.appendChild(titleEl);
 
-                // Create the child element for the excerpt
-                const textEl = document.createElement("p");
-                textEl.classList.add("pagefind-modular-list-excerpt");
-                textEl.innerHTML = result.excerpt;
-                innerEl.appendChild(textEl);
+                    const textEl = document.createElement("p");
+                    textEl.classList.add("pagefind-modular-list-excerpt");
+                    textEl.innerHTML = result.excerpt;
+                    linkEl.appendChild(textEl);
 
-                return el;
+                    return el;
+                }
+            }));
+        }
+
+        return function () {
+            if (!ready) {
+                const css = document.createElement("link");
+                css.rel = "stylesheet";
+                css.href = "/pagefind/pagefind-modular-ui.css";
+                document.head.appendChild(css);
+                ready = new Promise((resolve, reject) => {
+                    const script = document.createElement("script");
+                    script.src = "/pagefind/pagefind-modular-ui.js";
+                    script.onload = () => { initSearch(); resolve(); };
+                    script.onerror = reject;
+                    document.head.appendChild(script);
+                });
             }
-        }));
-    });
+            return ready;
+        };
+    })();
 </script>
diff --git a/ui/src/partials/head-scripts.hbs b/ui/src/partials/head-scripts.hbs
index f56c5cbf5..4456709a2 100644
--- a/ui/src/partials/head-scripts.hbs
+++ b/ui/src/partials/head-scripts.hbs
@@ -22,4 +22,3 @@
     -->
     {{/with}}
     <script>var uiRootPath = '{{{uiRootPath}}}'</script>
-    <script src="/pagefind/pagefind-modular-ui.js"></script>
diff --git a/ui/src/partials/head-styles.hbs b/ui/src/partials/head-styles.hbs
index 321a12378..0d00db309 100644
--- a/ui/src/partials/head-styles.hbs
+++ b/ui/src/partials/head-styles.hbs
@@ -1,4 +1,3 @@
     <link rel="preload" href="{{{uiRootPath}}}/font/noto-sans-latin-400-normal.woff2" as="font" type="font/woff2" crossorigin>
     <link rel="preload" href="{{{uiRootPath}}}/font/ibm-plex-mono-latin-600-normal.woff2" as="font" type="font/woff2" crossorigin>
     <link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
-    <link rel="stylesheet" href="/pagefind/pagefind-modular-ui.css">

From 399d741626e2312858c11f93750560ff45f7b4d7 Mon Sep 17 00:00:00 2001
From: Lars Francke <git@lars-francke.de>
Date: Tue, 28 Jul 2026 17:04:50 +0200
Subject: [PATCH 2/2] fix: Keep pagination and the end-of-life banner out of
 the search index

Both render inside the article element and were indexed with the page
content, polluting excerpts with navigation labels and banner text.
---
 ui/src/partials/article.hbs    | 2 +-
 ui/src/partials/pagination.hbs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/ui/src/partials/article.hbs b/ui/src/partials/article.hbs
index ca6899bc7..c52e5ab61 100644
--- a/ui/src/partials/article.hbs
+++ b/ui/src/partials/article.hbs
@@ -10,7 +10,7 @@ data-pagefind-body
 >
 {{! In antora.yml set asciidoc.attributes.page-end-of-life to true/false}}
 {{#if page.attributes.end-of-life}}
-<aside class="end-of-life-banner">
+<aside class="end-of-life-banner" data-pagefind-ignore>
   <h4>This version of the Stackable Data Platform is no longer maintained.</h4>
   <p>
     {{#if page.canonicalUrl}}
diff --git a/ui/src/partials/pagination.hbs b/ui/src/partials/pagination.hbs
index 4f6300f3a..a8afacef4 100644
--- a/ui/src/partials/pagination.hbs
+++ b/ui/src/partials/pagination.hbs
@@ -1,6 +1,6 @@
 {{#unless (eq page.attributes.pagination undefined)}}
 {{#if (or page.previous page.next)}}
-<nav class="pagination">
+<nav class="pagination" data-pagefind-ignore>
   {{#with page.previous}}
   <span class="prev"><a href="{{{relativize ./url}}}">{{{./content}}}</a></span>
   {{/with}}