feat: Implement search functionality with a modal interface, including search index generation and styling updates for improved user experience

Author: SirStig

scripts/build_docs_site.py

@@ -239,6 +239,68 @@ def scoped(style: str, theme: str) -> str:
     path.write_text("\n".join(chunks) + "\n", encoding="utf-8")
 
 
+def md_body_to_search_text(body: str, max_len: int = 16000) -> str:
+    t = body
+    t = re.sub(r"(?i)^\[TOC\]\s*\n*", "", t)
+    t = re.sub(r"<[^>]+>", " ", t)
+    t = re.sub(r"`+", " ", t)
+    t = re.sub(r"!\[([^\]]*)\]\([^)]*\)", r"\1 ", t)
+    t = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1 ", t)
+    t = re.sub(r"^#{1,6}\s*(\S.*?)\s*$", r"\1 ", t, flags=re.M)
+    t = re.sub(r"[*_~>|\\]+", " ", t)
+    t = re.sub(r"\s+", " ", t).strip()
+    return t[:max_len]
+
+
+def build_search_entries() -> list[dict[str, str]]:
+    records: list[dict[str, str]] = []
+    for _group_label, items in NAV:
+        for title, src in items:
+            if src == "__api__":
+                records.append(
+                    {
+                        "title": title,
+                        "href": site_href("api/index.html"),
+                        "text": (
+                            f"{title} Python API reference pdoc modules "
+                            "classes functions yokedcache"
+                        ),
+                    }
+                )
+                continue
+            md_path = PAGES_DIR / src
+            if not md_path.is_file():
+                raise FileNotFoundError(str(md_path))
+            raw = md_path.read_text(encoding="utf-8")
+            _meta, body = parse_frontmatter(raw)
+            plain = md_body_to_search_text(body)
+            records.append(
+                {
+                    "title": title,
+                    "href": site_href(md_to_html_path(src)),
+                    "text": f"{title} {plain}",
+                }
+            )
+    records.append(
+        {
+            "title": "Changelog",
+            "href": site_href("changelog.html"),
+            "text": "changelog release history versions fixes features migrations",
+        }
+    )
+    records.append(
+        {
+            "title": "Home",
+            "href": site_href("index.html"),
+            "text": (
+                "YokedCache async cache redis memcached memory disk sqlite "
+                "python fastapi starlette tag invalidation middleware metrics"
+            ),
+        }
+    )
+    return records
+
+
 def nav_context(current_out: str) -> list[dict]:
     groups = []
     for label, items in NAV:
@@ -275,6 +337,15 @@ def _skip_root_html(src: str, names: list[str]) -> set[str]:
         shutil.copytree(STATIC_DIR, OUT, dirs_exist_ok=True, ignore=_skip_root_html)
     shutil.copytree(ASSETS_DIR, OUT / "assets")
     write_syntax_highlight_css(OUT / "assets" / "syntax-highlight.css")
+    try:
+        search_entries = build_search_entries()
+    except FileNotFoundError as e:
+        print(f"Search index: missing {e}", file=sys.stderr)
+        return 1
+    (OUT / "assets" / "search-index.json").write_text(
+        json.dumps(search_entries, ensure_ascii=False, separators=(",", ":")),
+        encoding="utf-8",
+    )
 
     (OUT / ".nojekyll").write_text("", encoding="utf-8")
 
@@ -342,6 +413,7 @@ def _skip_root_html(src: str, names: list[str]) -> set[str]:
                 asset_style_href=site_href("assets/style.css"),
                 asset_syntax_href=site_href("assets/syntax-highlight.css"),
                 asset_script_href=site_href("assets/app.js"),
+                search_index_href=site_href("assets/search-index.json"),
                 home_href=site_href("index.html"),
                 changelog_href=site_href("changelog.html"),
                 api_href=site_href("api/index.html"),
@@ -365,6 +437,7 @@ def _skip_root_html(src: str, names: list[str]) -> set[str]:
         "maintainer_same_as": MAINTAINER_SAME_AS,
         "home_canonical": home_canonical,
         "changelog_canonical": f"{SITE_URL}/changelog.html",
+        "search_index_href": site_href("assets/search-index.json"),
     }
     for standalone in ("index.html.jinja2", "changelog.html.jinja2"):
         stpl = env.get_template(standalone)

site-src/assets/app.js

@@ -56,6 +56,9 @@ sidebar?.querySelectorAll(".sidebar-link").forEach((link) => {
 });
 
 document.addEventListener("keydown", (e) => {
+  if (e.key === "Escape" && document.getElementById("searchModal")?.open) {
+    return;
+  }
   if (e.key === "Escape" && drawerOpen()) {
     setDrawerOpen(false);
     menuBtn?.focus();
@@ -106,3 +109,142 @@ document.querySelectorAll(".code-block pre code").forEach((code) => {
   label.textContent = m[1];
   wrap.insertBefore(label, wrap.firstChild);
 });
+
+(function initDocSearch() {
+  const indexUrl = html.getAttribute("data-search-index");
+  const modal = document.getElementById("searchModal");
+  const openBtn = document.getElementById("searchOpenBtn");
+  const closeBtn = document.getElementById("searchCloseBtn");
+  const input = document.getElementById("searchInput");
+  const resultsEl = document.getElementById("searchResults");
+  const emptyHint = document.getElementById("searchEmptyHint");
+  const kbdHint = document.getElementById("searchKbdHint");
+
+  if (kbdHint) {
+    const mac = /Mac|iPhone|iPad|iPod/i.test(
+      navigator.platform || navigator.userAgentData?.platform || ""
+    );
+    kbdHint.textContent = mac ? "⌘K" : "Ctrl+K";
+  }
+
+  if (!indexUrl || !modal || !input || !resultsEl || typeof Fuse === "undefined") {
+    return;
+  }
+
+  let fuse = null;
+  let loadError = null;
+
+  function ensureFuse() {
+    if (fuse || loadError) return Promise.resolve();
+    return fetch(indexUrl)
+      .then((r) => {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.json();
+      })
+      .then((records) => {
+        fuse = new Fuse(records, {
+          keys: [
+            { name: "title", weight: 0.42 },
+            { name: "text", weight: 0.58 },
+          ],
+          threshold: 0.38,
+          ignoreLocation: true,
+          minMatchCharLength: 2,
+          includeScore: true,
+        });
+      })
+      .catch((err) => {
+        loadError = err;
+      });
+  }
+
+  function renderResults(q) {
+    resultsEl.innerHTML = "";
+    if (loadError) {
+      emptyHint.textContent = "Could not load search index.";
+      emptyHint.hidden = false;
+      return;
+    }
+    if (!fuse) {
+      emptyHint.textContent = "Loading…";
+      emptyHint.hidden = false;
+      return;
+    }
+    const query = q.trim();
+    if (query.length < 2) {
+      emptyHint.textContent = "Type at least 2 characters. Fuzzy matching handles typos.";
+      emptyHint.hidden = false;
+      return;
+    }
+    emptyHint.hidden = true;
+    const hits = fuse.search(query, { limit: 14 });
+    if (!hits.length) {
+      emptyHint.textContent = "No matches. Try different wording.";
+      emptyHint.hidden = false;
+      return;
+    }
+    const frag = document.createDocumentFragment();
+    hits.forEach(({ item }) => {
+      const li = document.createElement("li");
+      li.setAttribute("role", "option");
+      const a = document.createElement("a");
+      a.href = item.href;
+      a.className = "search-result-link";
+      const t = document.createElement("span");
+      t.className = "search-result-title";
+      t.textContent = item.title;
+      a.appendChild(t);
+      li.appendChild(a);
+      frag.appendChild(li);
+    });
+    resultsEl.appendChild(frag);
+  }
+
+  let debounceTimer = null;
+  function scheduleSearch() {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => renderResults(input.value), 60);
+  }
+
+  function openSearch() {
+    ensureFuse().then(() => {
+      modal.showModal();
+      input.focus();
+      if (loadError) {
+        renderResults("");
+        return;
+      }
+      input.select();
+      renderResults(input.value);
+    });
+  }
+
+  function closeSearch() {
+    modal.close();
+  }
+
+  openBtn?.addEventListener("click", () => openSearch());
+  closeBtn?.addEventListener("click", () => closeSearch());
+  input?.addEventListener("input", scheduleSearch);
+
+  modal.addEventListener("close", () => {
+    input.value = "";
+    resultsEl.innerHTML = "";
+    emptyHint.textContent = "Type to search. Fuzzy matching handles typos.";
+    emptyHint.hidden = false;
+  });
+
+  document.addEventListener("keydown", (e) => {
+    if (!(e.metaKey || e.ctrlKey) || (e.key !== "k" && e.key !== "K")) return;
+    const tag = e.target?.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || e.target?.isContentEditable) {
+      if (e.target !== input) return;
+    }
+    e.preventDefault();
+    if (modal.open) {
+      closeSearch();
+    } else {
+      openSearch();
+    }
+  });
+})();