From d02d832874599642d48a71a10b5f72de5c74c118 Mon Sep 17 00:00:00 2001
From: Seb Bacon <seb.bacon@gmail.com>
Date: Tue, 20 Jan 2026 15:09:56 +0000
Subject: [PATCH 1/2] feat: replace built-in search with Google Custom Search

Replace the MkDocs Material theme's Lunr.js search with Google Custom
Search Engine for improved search results across the documentation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/css/extra.css             | 59 ++++++++++++++++++++++++++++++++++
 overrides/main.html            |  5 +++
 overrides/partials/search.html |  3 ++
 3 files changed, 67 insertions(+)
 create mode 100644 overrides/partials/search.html

diff --git a/docs/css/extra.css b/docs/css/extra.css
index 77d59e4bc..e64c25df3 100644
--- a/docs/css/extra.css
+++ b/docs/css/extra.css
@@ -175,6 +175,65 @@ body {
   padding: 0;
 }
 
+/* Google Custom Search Engine styling */
+.md-search {
+  position: relative;
+}
+
+.gcse-search {
+  width: 100%;
+}
+
+/* Search input styling */
+.gsc-input-box {
+  border-radius: 4px !important;
+  border-color: var(--colorLightGrey) !important;
+  background-color: var(--colorWhite) !important;
+}
+
+.gsc-input {
+  font-family: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI",
+    Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif !important;
+}
+
+/* Search button styling */
+.gsc-search-button-v2 {
+  background-color: var(--colorPrimary) !important;
+  border-color: var(--colorPrimary) !important;
+  border-radius: 4px !important;
+  padding: 8px 16px !important;
+}
+
+.gsc-search-button-v2:hover {
+  background-color: var(--colorLightPrimary) !important;
+  border-color: var(--colorLightPrimary) !important;
+}
+
+/* Results styling */
+.gsc-result .gs-title,
+.gsc-result .gs-title a {
+  color: var(--colorLink) !important;
+  font-family: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI",
+    Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif !important;
+  text-decoration: underline !important;
+}
+
+.gsc-result .gs-title a:hover {
+  color: var(--colorLinkHover) !important;
+}
+
+.gsc-result .gs-snippet {
+  font-family: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI",
+    Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif !important;
+  color: var(--colorOffBlack) !important;
+}
+
+/* Hide Google branding if desired */
+.gsc-above-wrapper-area,
+.gcsc-more-maybe-branding-root {
+  display: none !important;
+}
+
 .footer-nav-buttons {
   border-top: 1px solid var(--colorLightGrey);
 
diff --git a/overrides/main.html b/overrides/main.html
index ba332b47f..e4afaaf48 100644
--- a/overrides/main.html
+++ b/overrides/main.html
@@ -1,5 +1,10 @@
 {% extends "base.html" %}
 
+{% block libs %}
+  {{ super() }}
+  <script async src="https://cse.google.com/cse.js?cx=1582fc3f4c0fd41c4"></script>
+{% endblock %}
+
 {% block fonts %}
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
 
diff --git a/overrides/partials/search.html b/overrides/partials/search.html
new file mode 100644
index 000000000..62cb014c2
--- /dev/null
+++ b/overrides/partials/search.html
@@ -0,0 +1,3 @@
+<div class="md-search" data-md-component="search" role="search">
+  <div class="gcse-search"></div>
+</div>

From 11a6c3d679f4a862e83f26a3255841387b6161f4 Mon Sep 17 00:00:00 2001
From: Seb Bacon <seb.bacon@gmail.com>
Date: Tue, 20 Jan 2026 16:15:33 +0000
Subject: [PATCH 2/2] fix: ensure Google CSE is visible in header

Override Material theme's default search visibility behavior to keep
the Google Custom Search always visible rather than toggle-based.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/css/extra.css             | 14 ++++++++++++++
 overrides/partials/search.html |  4 +++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/css/extra.css b/docs/css/extra.css
index e64c25df3..540f8aad5 100644
--- a/docs/css/extra.css
+++ b/docs/css/extra.css
@@ -178,12 +178,26 @@ body {
 /* Google Custom Search Engine styling */
 .md-search {
   position: relative;
+  display: block !important;
+  opacity: 1 !important;
+  transform: none !important;
+  width: auto !important;
+  max-width: 400px;
+}
+
+.md-search__inner {
+  display: block !important;
 }
 
 .gcse-search {
   width: 100%;
 }
 
+/* Hide the default search toggle icon since CSE is always visible */
+.md-header__button[for="__search"] {
+  display: none;
+}
+
 /* Search input styling */
 .gsc-input-box {
   border-radius: 4px !important;
diff --git a/overrides/partials/search.html b/overrides/partials/search.html
index 62cb014c2..baddf105e 100644
--- a/overrides/partials/search.html
+++ b/overrides/partials/search.html
@@ -1,3 +1,5 @@
 <div class="md-search" data-md-component="search" role="search">
-  <div class="gcse-search"></div>
+  <div class="md-search__inner">
+    <div class="gcse-search"></div>
+  </div>
 </div>