Replace Sphinx search with Pagefind

Sphinx's stock client-side search stems and splits identifiers like
`system.nix` into ubiquitous terms (`system` + `nix`) and stores no
positional data, so phrase/identifier ranking is impossible: searching
`system.nix` did not rank `guides/recipes/dependency-management.html`,
which contains the exact string.

Pagefind indexes the rendered HTML post-build and does real
phrase/proximity ranking. Searching `system.nix` now ranks that page
first.

- `pagefind.yml`: scope indexing to the article body, exclude UI chrome.
- `default.nix`: add `pkgs.pagefind` to `nativeBuildInputs` (also exposes
  it in the dev shell via `inputsFrom`).
- `Makefile`: run `pagefind --site build/html` after `sphinx-build` in the
  `html` target for local/CI parity, guarded with a clear error if the
  binary is missing.
- `source/_templates/search.html`: replace the Sphinx search page with a
  Pagefind UI, dropping the now-unused Sphinx search scripts and
  pre-filling from `?q=` so the sidebar search box still works.

Assisted-by: Claude:claude-opus-4-8

Author: KiaraGrouwstra

Makefile

@@ -60,6 +60,11 @@ html:
 	# hack to make live-reload on css update work
 	@cp source/_static/css/custom.css build/html/_static/css/custom.css
 
+	# build the Pagefind search index over the rendered HTML (writes build/html/_pagefind/)
+	@command -v pagefind >/dev/null 2>&1 \
+		|| { echo "error: 'pagefind' not found on PATH; install it or run inside the Nix dev shell (nix-shell)"; exit 1; }
+	pagefind --site build/html
+
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

default.nix

@@ -36,6 +36,7 @@ let
     nativeBuildInputs = [
       nix-dev-python-pkgs
       nix-dev-latex
+      pkgs.pagefind
     ];
     buildPhase =
       let

pagefind.yml

@@ -0,0 +1,14 @@
+# Pagefind configuration for nix.dev search.
+# `--site build/html` is passed on the CLI (see Makefile / default.nix),
+# so this file only holds selectors and tuning.
+
+# Only index the main article content, not navigation/sidebars/footers.
+root_selector: "div.bd-article-container"
+
+# Keep search snippets clean by dropping non-content UI bits.
+exclude_selectors:
+  - "a.headerlink"
+  - "button.copybtn"        # sphinx_copybutton buttons
+  - ".prev-next-footer"
+
+force_language: "en"

source/_templates/search.html

@@ -0,0 +1,38 @@
+{# Replace Sphinx's built-in search page with a Pagefind-powered one. #}
+{# Overrides the theme's search.html (pydata_sphinx_theme), which itself #}
+{# overrides the `docs_body` block; see pydata_sphinx_theme/search.html.  #}
+{% extends "!search.html" %}
+
+{% block docs_body %}
+<div class="bd-search-container">
+  <h1>{{ _("Search") }}</h1>
+  <noscript>
+    <div class="admonition error">
+      <p class="admonition-title">{% trans %}Error{% endtrans %}</p>
+      <p>{% trans %}Please activate JavaScript to enable the search functionality.{% endtrans %}</p>
+    </div>
+  </noscript>
+  <link rel="stylesheet" href="{{ pathto('pagefind/pagefind-ui.css', 1) }}">
+  <div id="search" class="pagefind-search"></div>
+  <script src="{{ pathto('pagefind/pagefind-ui.js', 1) }}"></script>
+  <script>
+    window.addEventListener('DOMContentLoaded', () => {
+      const search = new PagefindUI({ element: "#search", showSubResults: true, excerptLength: 30 });
+      // Pre-fill from `?q=` so the theme's sidebar search box (which submits to
+      // this page) carries the query through to the Pagefind results.
+      const q = new URLSearchParams(window.location.search).get("q");
+      if (q) {
+        search.triggerSearch(q);
+      }
+    });
+  </script>
+</div>
+{% endblock docs_body %}
+
+{# The theme's search.html pulls in Sphinx's searchtools.js / searchindex.js #}
+{# via the `scripts` block. We use Pagefind instead, so emit only the standard #}
+{# document scripts (Sphinx's base `scripts` block is just `script()`) and drop #}
+{# the now-unused Sphinx search index. #}
+{% block scripts %}
+  {{- script() }}
+{% endblock scripts %}