docs(html): add in-browser topbar search via pagefind

grandixximo · grandixximo · commit 6e5ec62e8a7e · 2026-06-20T15:25:09.000+08:00
Build a per-language pagefind index at htmldocs time (optional: only when pagefind is on PATH, which CI installs) and add a topbar search box that loads its language's index. Topbar chrome is excluded from the index. Includes theme-aware styling and a color-scheme dark-theme fix for the translucent bar.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -171,6 +171,16 @@ jobs:
       run: |
         set -x
         .github/scripts/install-deps.sh
+    - name: Install pagefind (docs search index)
+      run: |
+        set -x
+        PAGEFIND_VERSION=v1.5.2
+        tmp="$(mktemp -d)"
+        curl --no-progress-meter -fL \
+          "https://github.com/Pagefind/pagefind/releases/download/$PAGEFIND_VERSION/pagefind-$PAGEFIND_VERSION-x86_64-unknown-linux-musl.tar.gz" \
+          | tar -xz -C "$tmp"
+        sudo install -m 0755 "$tmp/pagefind" /usr/local/bin/pagefind
+        rm -rf "$tmp"
     - name: Build HTML docmentation
       run: |
         set -x
diff --git a/docs/src/Submakefile b/docs/src/Submakefile
@@ -67,6 +67,15 @@ DOC_MAN       := $(DOC_BUILD)/man
 # PDFs live under the html tree (docs/build/html/<lang>/pdf/) so the html
 # subtree is self-contained and can link them with relative paths.
 
+# Pagefind powers the in-browser docs search box in the topbar.  It is a
+# Rust binary distributed via npm/GitHub, not a Debian package, so it cannot
+# be a hard Build-Depends: the build detects it on PATH and only wires search
+# in when present.  Official .deb builds without pagefind simply ship docs
+# without the search box; CI installs it explicitly for the htmldocs job.
+# Defined here (early) because the search-box substitution and the index
+# stamp below both gate on it via parse-time ifeq/ifneq.
+PAGEFIND := $(shell command -v pagefind 2>/dev/null)
+
 ASCIIDOCTOR_DEFAULT_CSS := $(shell ruby -e 'require "asciidoctor"; print Asciidoctor::DATA_DIR' 2>/dev/null)/stylesheets/asciidoctor-default.css
 
 # The following line determines for the Makefile what languages should be addressed.
@@ -595,6 +604,31 @@ endif
 .htmldoc-stamp: .copy-asciidoc-stamp $(DOC_DIR)/.gen_complist-stamp $(HTML_TARGETS) .images-stamp .include-stamp $(DOC_OUT_HTML)/asciidoctor.css $(DOC_OUT_HTML)/rouge-github.css .lang-switcher-stamp
 	touch $@
 
+# In-browser search index.  Runs over the finished HTML tree (after all
+# post-processing), so it depends on .htmldoc-stamp.  One index is built per
+# language subtree (en/_pagefind, de/_pagefind, ...) rather than a single
+# index at the tree root: a merged index makes pagefind treat its largest
+# (primary) language as a catch-all that returns every language, so the topbar
+# search on an English page would surface German, Chinese, ... hits.  A
+# per-language index physically contains only that language, so each page
+# loads its own subtree's index and results stay in one language.  Each
+# _pagefind bundle (wasm + index shards + UI js/css) is self-contained; the
+# HTML is never modified, so a second build is a no-op.  Gated on HTML docs
+# being enabled and pagefind installed; when absent the topbar carries no
+# search box (see @SEARCH_BOX@ above).
+ifeq ($(BUILD_DOCS_HTML),yes)
+ifneq ($(PAGEFIND),)
+htmldocs: .pagefind-stamp
+.pagefind-stamp: .htmldoc-stamp
+	$(Q)rm -rf $(DOC_OUT_HTML)/pagefind
+	$(Q)for lang in en $(LANGUAGES); do \
+		rm -rf $(DOC_OUT_HTML)/$$lang/_pagefind; \
+		$(PAGEFIND) --site $(DOC_OUT_HTML)/$$lang --output-subdir _pagefind || exit $$?; \
+	done
+	@touch $@
+endif
+endif
+
 # Inject the whole-document sidebar/topbar and grey out missing language-
 # switcher entries.  Runs last (depends on every HTML target) and is
 # idempotent.  Gated on BUILD_DOCS_HTML, not translations: the sidebar comes
@@ -626,12 +660,13 @@ SHARED_HTML_ASSETS = \
 
 # docinfo-header.html: generated from .in template.  The @LANGUAGE_SWITCHER@
 # placeholder expands to one <li> per language (English plus everything
-# in $(LANGUAGES)), labelled via $(LANG_LABEL_<lang>).  asciidoctor then
-# substitutes the {lcnc-cssrel} / {lcnc-lang-label} / {lcnc-subpath}
-# attributes per page.  po4a.cfg drives the language list, lang-labels
-# the display names.
-$(DOC_SRCDIR)/docinfo-header.html: $(DOC_SRCDIR)/docinfo-header.html.in $(DOC_DIR)/po4a.cfg $(LANG_LABEL_FILE) $(DOC_SRCDIR)/Submakefile
-	@block=$$(mktemp); \
+# in $(LANGUAGES)), labelled via $(LANG_LABEL_<lang>).  @SEARCH_BOX@ expands
+# to the pagefind search widget when pagefind is installed, else to nothing.
+# asciidoctor then substitutes the {lcnc-cssrel} / {lcnc-lang-label} /
+# {lcnc-subpath} attributes per page.  po4a.cfg drives the language list,
+# lang-labels the display names.
+$(DOC_SRCDIR)/docinfo-header.html: $(DOC_SRCDIR)/docinfo-header.html.in $(DOC_SRCDIR)/search-box.html $(DOC_DIR)/po4a.cfg $(LANG_LABEL_FILE) $(DOC_SRCDIR)/Submakefile
+	@block=$$(mktemp); sbox=$$(mktemp); \
 	    printf '  <div class="lcnc-lang-switcher">\n' > $$block ; \
 	    printf '    <input type="checkbox" id="lcnc-lang-toggle" class="lcnc-lang-toggle">\n' >> $$block ; \
 	    printf '    <label for="lcnc-lang-toggle" class="lcnc-lang-label">{lcnc-lang-label}</label>\n' >> $$block ; \
@@ -640,11 +675,13 @@ $(DOC_SRCDIR)/docinfo-header.html: $(DOC_SRCDIR)/docinfo-header.html.in $(DOC_DI
 	    $(foreach L,$(LANGUAGES),printf '      <li><a href="{lcnc-cssrel}$(L)/{lcnc-subpath}">$(LANG_LABEL_$(L))</a></li>\n' >> $$block ;) \
 	    printf '    </ul>\n' >> $$block ; \
 	    printf '  </div>\n' >> $$block ; \
-	    awk -v block="$$block" ' \
+	    $(if $(PAGEFIND),cat $(DOC_SRCDIR)/search-box.html > $$sbox,: > $$sbox) ; \
+	    awk -v block="$$block" -v sbox="$$sbox" ' \
 	      /@LANGUAGE_SWITCHER@/ { while ((getline line < block) > 0) print line; next } \
+	      /@SEARCH_BOX@/ { while ((getline line < sbox) > 0) print line; next } \
 	      { print } \
 	    ' $< > $@ ; \
-	    rm -f $$block
+	    rm -f $$block $$sbox
 
 # Stamp-gated asset copy; copy_asciidoc_files stays as a phony alias.
 # The en/gcode.html copy lives in its own rule above so it fires for PDF-only
diff --git a/docs/src/docinfo-header.html.in b/docs/src/docinfo-header.html.in
@@ -1,4 +1,4 @@
-<header id="lcnc-topbar" class="lcnc-topbar">
+<header id="lcnc-topbar" class="lcnc-topbar" data-pagefind-ignore>
   <a class="lcnc-topbar-home" href="{lcnc-cssrel}index.html">
     <img src="{lcnc-cssrel}lcnc-docs.svg" alt="LinuxCNC Documentation">
   </a>
@@ -13,5 +13,6 @@
     <span class="lcnc-sep" aria-hidden="true">&bull;</span>
     <a data-lcnc-link="4" href="{lcnc-cssrel}en/gcode.html">G-Code Quick Reference</a>
   </nav>
+@SEARCH_BOX@
 @LANGUAGE_SWITCHER@
 </header>
diff --git a/docs/src/lcnc-overrides.css b/docs/src/lcnc-overrides.css
@@ -10,6 +10,14 @@
    index.html / gcode.html.
 */
 
+/* Declare both schemes and pin the root background per theme so the canvas
+   behind the translucent topbar is deterministic (no auto-dark flash). */
+:root { color-scheme: light dark; }
+html { background: #fff; }
+@media (prefers-color-scheme: dark) {
+  html { background: #1e1e1e; }
+}
+
 /* ======================================================================
  *  Asciidoctor pages (light)
  * ====================================================================== */
@@ -769,4 +777,182 @@ h4,h5{font-size:revert}}
 .imageblock.text-center > .title { text-align: center; }
 .imageblock.text-right  > .title { text-align: right; }
 .imageblock             > .title { margin-top: 0.5em;}
+
+/* Pagefind search box in the topbar (present only when built with pagefind).
+   Theming flows through pagefind's CSS variables. */
+.lcnc-topbar-search {
+  margin-left: auto;
+  margin-right: 0.75rem;
+  position: relative;
+  display: flex;
+  align-items: center;
+  height: 100%;
+  font-family: "Open Sans","DejaVu Sans",sans-serif;
+  /* The bar is always dark, so the box sits on dark in both themes.  Size via
+     pagefind's scale, not an input height override (that desyncs the
+     absolutely-positioned magnifier/clear). */
+  --pagefind-ui-scale: 0.6;
+  --pagefind-ui-background: transparent;
+  --pagefind-ui-text: #fff;          /* input text + magnifier on the dark bar */
+  --pagefind-ui-primary: #fff;
+  --pagefind-ui-border: hsla(0,0%,100%,.35);
+  --pagefind-ui-tag: hsla(0,0%,100%,.15);
+  --pagefind-ui-border-width: 1px;
+  --pagefind-ui-border-radius: 4px;
+  --pagefind-ui-font: "Open Sans","DejaVu Sans",sans-serif;
+}
+/* Search + language switcher form one right-aligned cluster; zero the
+   switcher's own margin-left:auto so it does not split the free space. */
+.lcnc-topbar-search + .lcnc-lang-switcher { margin-left: 0; }
+.lcnc-topbar-search #lcnc-search { width: 13rem; }
+/* #lcnc-topbar (id) outranks pagefind-ui.css (injected after this sheet).
+   The input is a faint white inset on the dark bar. */
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-input {
+  background: hsla(0,0%,100%,.1);
+  color: #d8d8d8; /* typed text: a smudge off pure white, both themes */
+  border-color: hsla(0,0%,100%,.35);
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-input:focus {
+  background: hsla(0,0%,100%,.16);
+  border-color: hsla(0,0%,100%,.55);
+  /* replace the OS-accent (blue) focus ring with a neutral white halo */
+  outline: none;
+  box-shadow: 0 0 0 2px hsla(0,0%,100%,.18);
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-input::placeholder { color: hsla(0,0%,100%,.7); }
+/* neutral selection tint (avoid the OS-accent blue) */
+.lcnc-topbar-search ::selection { background: hsla(0,0%,100%,.25); color: #fff; }
+/* Pagefind's clear control is a "Clear" text button; hide the word and draw a
+   small white x (background-image SVG, font-independent). */
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-clear {
+  font-size: 0;
+  background: transparent;
+  display: flex;
+  align-items: center;
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-clear::after {
+  content: "";
+  display: block;
+  width: 13px;
+  height: 13px;
+  opacity: 0.7;
+  background-image: var(--lcnc-x-icon);
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: contain;
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-clear:hover::after { opacity: 1; }
+.lcnc-topbar-search {
+  --lcnc-x-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3E%3Cpath d='M5 5 L15 15 M15 5 L5 15' stroke='white' stroke-width='2.2' stroke-linecap='round'/%3E%3C/svg%3E");
+  --lcnc-search-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='white' stroke-width='2'%3E%3Ccircle cx='10' cy='10' r='7'/%3E%3Cline x1='15' y1='15' x2='20.5' y2='20.5' stroke-linecap='round'/%3E%3C/svg%3E");
+}
+/* Pagefind masks the magnifier with -webkit-mask, which Firefox/Zen render
+   blank.  Use a plain background-image SVG instead (works in every engine);
+   pagefind's ::before size/position are kept. */
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__form::before {
+  background-color: transparent;
+  -webkit-mask: none;
+  mask: none;
+  background-image: var(--lcnc-search-icon);
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: contain;
+  opacity: 0.9;
+}
+/* Results drawer floats below the input.  It is themed to match the page
+   (light/dark), unlike the always-dark bar; redefining --pagefind-ui-text on
+   the drawer recolours all result text in one shot. */
+.lcnc-topbar-search .pagefind-ui__drawer {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  width: 30rem;
+  max-height: 75vh;
+  overflow-y: auto;
+  border-radius: 0 0 6px 6px;
+  padding: 0.5em 0.85em 0.85em;
+  z-index: 1200;
+  --pagefind-ui-text: #222;
+  background: #fff;
+  color: #222;
+  border: 1px solid #d4d4d4;
+  border-top: none;
+  box-shadow: 0 6px 16px rgba(0,0,0,.18);
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link,
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link:link { color: #2156a5; }
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link:visited { color: #1d4b8f; }
+.lcnc-topbar-search .pagefind-ui__result-excerpt { color: #555; }
+.lcnc-topbar-search .pagefind-ui__message { color: #555; }
+/* Landing pages style bare p/ul/li generically and that leaks into the drawer;
+   re-assert result metrics at id specificity so it looks the same everywhere. */
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-title {
+  font-size: 1rem;
+  line-height: 1.25;
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-excerpt,
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__message {
+  font-size: 0.85rem;
+  line-height: 1.45;
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__drawer ul {
+  font-family: inherit;
+  margin: 0;
+  padding: 0;
+}
+#lcnc-topbar .lcnc-topbar-search .pagefind-ui__drawer li {
+  line-height: normal;
+  margin-top: 0;
+}
+/* soften pagefind's hard-yellow match highlight to a translucent wash */
+.lcnc-topbar-search .pagefind-ui__result mark,
+.lcnc-topbar-search mark {
+  background: hsla(48,100%,50%,.30);
+  color: inherit;
+  padding: 0 1px;
+  border-radius: 2px;
+}
+@media (prefers-color-scheme: dark) {
+  /* Pin the pocket to solid fill + border.  A translucent pocket on the
+     translucent bar cold-paints inconsistently dark in Firefox/Zen; solid
+     values matching the settled look keep it backdrop-independent.  The bar
+     itself stays translucent. */
+  #lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-input {
+    background: #1f1f1f;
+    border-color: #5d5d5d;
+  }
+  #lcnc-topbar .lcnc-topbar-search .pagefind-ui__search-input:focus {
+    background: #2e2e2e;
+    border-color: #8a8a8a;
+  }
+  .lcnc-topbar-search .pagefind-ui__drawer {
+    --pagefind-ui-text: #e0e0e0;
+    background: #1e1e1e;
+    color: #e0e0e0;
+    border-color: #444;
+    box-shadow: 0 6px 16px rgba(0,0,0,.5);
+  }
+  #lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link,
+  #lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link:link { color: #6fa8dc; }
+  #lcnc-topbar .lcnc-topbar-search .pagefind-ui__result-link:visited { color: #b48ead; }
+  .lcnc-topbar-search .pagefind-ui__result-excerpt { color: #aaa; }
+  .lcnc-topbar-search .pagefind-ui__message { color: #aaa; }
+  .lcnc-topbar-search .pagefind-ui__result mark,
+  .lcnc-topbar-search mark {
+    background: hsla(48,90%,55%,.25);
+    color: inherit;
+  }
+}
+/* The nav links are absolutely centred and ignore the right-hand cluster's
+   width, so the search box needs more clearance than the bare 900px the nav
+   normally hides at.  Hide the nav earlier, but only in builds that actually
+   carry a search box (pagefind installed); :has keeps the 900px default for
+   search-less builds. */
+@media (max-width: 1300px) {
+  .lcnc-topbar:has(.lcnc-topbar-search) .lcnc-topbar-links { display: none; }
+}
+@media (max-width: 1100px) { .lcnc-topbar-search #lcnc-search { width: 10rem; } }
+@media (max-width: 700px) {
+  .lcnc-topbar-search .pagefind-ui__drawer { width: 88vw; }
+}
   
diff --git a/docs/src/search-box.html b/docs/src/search-box.html
@@ -0,0 +1,47 @@
+  <div class="lcnc-topbar-search">
+    <div id="lcnc-search"></div>
+    <script>
+      window.addEventListener("DOMContentLoaded", function () {
+        // One pagefind index is built per language subtree (en/_pagefind,
+        // de/_pagefind, ...) so search results stay in a single language.  Load
+        // the index for THIS page's language, picked from <html lang>: the UI
+        // assets and the index live in <lang>/_pagefind/ off the html root.
+        var cssrel = "{lcnc-cssrel}";
+        var pageLang = document.documentElement.lang || "en";
+        var pfBase = cssrel + pageLang + "/_pagefind/";
+
+        // Result URLs are stored root-relative with the language dir included
+        // ("/en/man/..."), so rewrite them against {lcnc-cssrel} to be relative
+        // to the current page; that keeps links working under any deployment
+        // path prefix.  sub_results carry their own URLs and need it too.
+        var rel = function (u) { return cssrel + u.replace(/^\//, ""); };
+
+        var link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = pfBase + "pagefind-ui.css";
+        document.head.appendChild(link);
+
+        var script = document.createElement("script");
+        script.src = pfBase + "pagefind-ui.js";
+        script.onload = function () {
+          new PagefindUI({
+            element: "#lcnc-search",
+            // No bundlePath: pagefind-ui.js auto-derives the index location from
+            // its own script src (loaded from pfBase above).  An explicit
+            // page-relative bundlePath would be re-resolved against the script
+            // URL and double-count the path.
+            showImages: false,
+            showSubResults: true,
+            processResult: function (result) {
+              result.url = rel(result.url);
+              if (result.sub_results) {
+                result.sub_results.forEach(function (s) { s.url = rel(s.url); });
+              }
+              return result;
+            }
+          });
+        };
+        document.body.appendChild(script);
+      });
+    </script>
+  </div>
