feat: add disable_search theme option

Add a new boolean theme option `disable_search` (default: `False`) that
allows users to completely remove the built-in PyData search dialog and
its associated navbar button. This is useful when a third-party search
addon provides its own UI and keyboard shortcut, such as the Read the
Docs server-side search addon, which would otherwise conflict with
PyData's dialog and Ctrl+K handler.

Changes:
- theme.conf: add `disable_search = False` option
- layout.html: wrap `#pst-search-dialog` in a new `{% block
  search_dialog %}` block gated on `theme_disable_search`. The dedicated
  block also gives downstream themes/overrides a clean extension point
  without copying the entire `content` block.
- pydata-sphinx-theme.js: add null-guards in `toggleSearchField()` and
  `setupSearchButtons()` so both functions are safe when the dialog
  element is absent. Previously both functions unconditionally queried
  `#pst-search-dialog`, throwing a `TypeError` if the element was not
  in the DOM.
- __init__.py: when `disable_search=True`, automatically remove
  `search-button-field` from `navbar_persistent` so the user only needs
  to set one option.

Closes: #202
Related: #795, #1933
Signed-off-by: Philip Schmid <phisch@cisco.com>

Author: PhilipSchmid

src/pydata_sphinx_theme/__init__.py

@@ -48,6 +48,18 @@ def update_config(app):
             "a value (leave undefined), or set to an empty list."
         )
 
+    # When search is disabled, remove the built-in search button from the navbar
+    # so the user only needs to set one option instead of also clearing navbar_persistent.
+    if theme_options.get("disable_search", False):
+        navbar_persistent = theme_options.get(
+            "navbar_persistent", ["search-button-field"]
+        )
+        if isinstance(navbar_persistent, str):
+            navbar_persistent = [s.strip() for s in navbar_persistent.split(",")]
+        theme_options["navbar_persistent"] = [
+            t for t in navbar_persistent if t.strip() != "search-button-field"
+        ]
+
     # Set the anchor link default to be # if the user hasn't provided their own
     if not utils.config_provided_by_user(app, "html_permalinks_icon"):
         app.config.html_permalinks_icon = "#"

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -185,6 +185,10 @@ var toggleSearchField = () => {
   // if the input field is the hidden one (the one associated with the
   // search button) then toggle the button state (to show/hide the field)
   const searchDialog = document.getElementById("pst-search-dialog");
+  if (!searchDialog) {
+    // Search dialog was disabled via disable_search theme option; nothing to do.
+    return;
+  }
   const hiddenInput = searchDialog.querySelector("input");
   if (input === hiddenInput) {
     if (searchDialog.open) {
@@ -301,6 +305,10 @@ var setupSearchButtons = () => {
 
   // If user clicks outside the search modal dialog, then close it.
   const searchDialog = document.getElementById("pst-search-dialog");
+  if (!searchDialog) {
+    // Search dialog was disabled via disable_search theme option; nothing to do.
+    return;
+  }
   // Dialog click handler includes clicks on dialog ::backdrop.
   searchDialog.addEventListener("click", closeDialogOnBackdropClick);
 };

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -69,10 +69,17 @@
   </button>
   {%- endif %}
 
-  {# A search field pop-up that will only show when the search button is clicked #}
+  {%- block search_dialog %}
+  {# A search field pop-up that will only show when the search button is clicked. #}
+  {# Set disable_search = True in html_theme_options to omit this dialog entirely, #}
+  {# e.g. when using a third-party search addon (such as Read the Docs server-side #}
+  {# search) that provides its own UI and keyboard shortcut. #}
+  {%- if not theme_disable_search | tobool %}
   <dialog id="pst-search-dialog">
     {% include "../components/search-field.html" %}
   </dialog>
+  {%- endif %}
+  {%- endblock search_dialog %}
 
   {% include "sections/announcement.html" %}
 

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -36,6 +36,7 @@ logo =
 logo_link =
 surface_warnings = True
 back_to_top_button = True
+disable_search = False
 search_as_you_type = False
 shorten_urls = True