#607: Pagefind Search (#615)

* Issue #607: proof of concept for site search with pagefind

* Build pagefind search index in doc/Makefile

* more gracefully handle missing doc/themes

* fix unwanted interactions between pagefind ui css and theme styles

* Make search controlled by a config switch

* Restore original handling for missing themes in Makefile

* update outer Makefile to build pagefind for doc site

* fix whitespace in doc/Makefile

* only show search affordance when search is enabled

* set search affordance title on the button

* disable search by default, only enable for doc site

* use native dialog element to show search input in a modal popover dialog

* remove now unnecessary Esc key handler for closing search dialog

* use npx --yes flag instead of piping yes

* remove unused js variable

* move search css into a dedicated static css file

* remove unused standalone search.js

* restore search css to search partial as it was failing CI (but not dev) build

* split search css into a separate css document

* whitespace change in new css file to satisfy prettier precommit hook

* split search js into a separate javascript file

* change single to double quotes in search.js to satisfy prettier

* unset pagefind color setting for dark mode without referring to internal pagefind svelte

* Inform user when pagefind is being installed

* ensure every page includes the search form when enabled

---------

Co-authored-by: Stefan van der Walt <[email protected]>

Author: brianhawthorne

.gitignore

@@ -6,3 +6,6 @@ resources
 # Auto-generated
 doc/content/shortcodes.md
 public
+
+# vim droppings
+.*.swp

Makefile

@@ -5,6 +5,7 @@ GH_ORG = scientific-python
 TEAMS_DIR = doc/content/about
 TEAMS = theme-team
 TEAMS_QUERY = python tools/team_query.py
+SEARCH = (echo "Installing \`pagefind\` and generating search index..." && npx --yes pagefind --site public)
 
 $(TEAMS_DIR):
 	mkdir -p $(TEAMS_DIR)
@@ -26,7 +27,10 @@ doc/content/shortcodes.md: $(wildcard layouts/shortcodes/*.html)
 # Serve for development purposes.
 serve-dev: doc-serve
 doc-serve: doc/content/shortcodes.md
-	(cd doc && hugo --printI18nWarnings serve --themesDir="../.." --disableFastRender --poll 1000ms)
+	(cd doc; \
+	hugo --themesDir="../.."; \
+	$(SEARCH); \
+	hugo --printI18nWarnings serve --themesDir="../.." --disableFastRender --poll 1000ms)
 
 # -----------------------------------
 # The following is for use on netlify
@@ -44,7 +48,7 @@ preview-theme:
 	python tools/add_preview_links.py
 
 theme: doc/content/shortcodes.md
-	(cd doc ; hugo --themesDir="../..")
+	(cd doc ; hugo --themesDir="../.."; $(SEARCH))
 
 scipy:
 	rm -rf $@

assets/js/search.js

@@ -0,0 +1,56 @@
+"use strict";
+
+window.addEventListener("DOMContentLoaded", () => {
+  let searchDialog = document.querySelector(".search-dialog");
+
+  // Do nothing here if search is not enabled.
+  if (!searchDialog) return;
+
+  new PagefindUI({
+    element: ".search-dialog",
+    autofocus: true,
+    resetStyles: false,
+    showSubResults: true,
+  });
+
+  let showSearch = () => searchDialog.showModal();
+  let hideSearch = () => searchDialog.close();
+
+  let toggleSearch = () => {
+    if (!searchDialog.open) {
+      showSearch();
+    } else {
+      hideSearch();
+    }
+  };
+
+  let isClickOutside = (elem, clickEvt) => {
+    const elemDims = elem.getBoundingClientRect();
+    return (
+      clickEvt.clientX < elemDims.left ||
+      clickEvt.clientX > elemDims.right ||
+      clickEvt.clientY < elemDims.top ||
+      clickEvt.clientY > elemDims.bottom
+    );
+  };
+
+  // Close the search dialog if user clicks outside of it when it is open.
+  // This feels like functionality that should really be natively supported
+  // by the dialog element already.
+  // https://blog.webdevsimplified.com/2023-04/html-dialog/
+  searchDialog.addEventListener("click", (evt) => {
+    if (searchDialog.open && isClickOutside(searchDialog, evt)) {
+      hideSearch();
+    }
+  });
+
+  window.addEventListener("keydown", (evt) => {
+    if (evt.key === "k" && evt.ctrlKey) {
+      toggleSearch();
+    }
+  });
+
+  document
+    .querySelector(".search-button")
+    .addEventListener("click", showSearch);
+});

assets/theme-css/search.css

@@ -0,0 +1,26 @@
+.search-button {
+  border-radius: 20px;
+  padding: 8px;
+  margin-right: 15px;
+  cursor: pointer;
+}
+.search-dialog {
+  padding: 15px;
+  width: 80%;
+  border-radius: 1rem;
+}
+.search-dialog::backdrop {
+  background-color: rgb(0, 0, 0, 0.5);
+  backdrop-filter: blur(3px);
+}
+.search-dialog input {
+  padding: 10px 15px;
+  color: #333;
+}
+.pagefind-ui button {
+  border: none;
+}
+/* unset a pagefind color setting to make results more legible in dark mode */
+.pagefind-ui__result-title > .pagefind-ui__result-link {
+  color: unset !important;
+}

config.yaml

@@ -7,6 +7,7 @@ params:
   images:
     - /images/logo.svg
   navColor: blue
+  search: false
   plausible:
     dataDomain: null
     javaScript: "https://views.scientific-python.org/js/script.js"

doc/Makefile

@@ -24,10 +24,11 @@ themes: themes/scientific-python-hugo-theme
 html: ## Build site in `./public`
 html: themes content/shortcodes.md
 	hugo
+	npx --yes pagefind --site public
 
 serve: ## Serve site, typically on http://localhost:1313
-serve: themes content/shortcodes.md
-	@hugo --printI18nWarnings server
+serve: html
+	@hugo --printI18nWarnings serve
 
 clean: ## Remove built files
 clean:

doc/config.yaml

@@ -21,6 +21,7 @@ params:
   description: "Documentation & template site for the Scientific Python Hugo Theme."
   images:
     - /images/logo.svg
+  search: true
   navbarlogo:
     image: logo.svg
     text: Scientific Python Hugo Theme

layouts/_default/baseof.html

@@ -32,6 +32,10 @@
     {{ partial "navbar.html" . -}}
     {{ end }}
 
+    {{ if .Site.Params.search }}
+    {{ partial "search.html" . }}
+    {{ end }}
+
     {{ block "main" . }}
     {{ end }}
 

layouts/partials/css.html

@@ -30,7 +30,8 @@
                     (resources.Get "theme-css/pst/pydata-sphinx-theme.scss")
                     (resources.Get "theme-css/spht/index.scss")
                     (resources.Match "theme-css/*.scss")
-           | append (resources.Match "css/*.scss") -}}
+           | append (resources.Match "css/*.scss")
+-}}
 
 {{- range $sass -}}
   {{ with . }}  <!-- Skips nil elements from appending empty resources.Match slices. -->

layouts/partials/javascript.html

@@ -5,7 +5,7 @@
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
 
 <!-- Custom JS -->
-<!-- All JS files under static/js are included -->
+<!-- All JS files under assets/js are included -->
 {{- $jsFiles := collections.Sort (resources.Match "js/*.js") "Name" -}}
 {{- if $inServerMode -}}
 {{- $js := $jsFiles | resources.Concat "js/bundle.js" }}