feat: add disable_search theme option (#2315)

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Author: PhilipSchmid

docs/user_guide/search.rst

@@ -74,3 +74,36 @@ Set the ``search_as_you_type`` HTML theme option to ``True``.
    html_theme_options = {
        "search_as_you_type": True
    }
+
+Disable the built-in search
+---------------------------
+
+If your site uses a third-party search backend (e.g. the `Read the Docs
+server-side search addon <https://docs.readthedocs.com/platform/stable/addons.html>`_),
+you may want to disable the built-in pydata search entirely. Set the
+``disable_search`` HTML theme option to ``True``:
+
+.. code:: python
+
+   html_theme_options = {
+       "disable_search": True
+   }
+
+This does two things automatically:
+
+* The ``#pst-search-dialog`` overlay is omitted from the page, so the
+  built-in search dialog never appears and keyboard shortcuts (:kbd:`Ctrl` +
+  :kbd:`K` / :kbd:`⌘` + :kbd:`K`) do not open it.
+* ``navbar_persistent`` is set to an empty list, so the default search button
+  is no longer rendered in the navbar.
+
+.. note::
+
+   ``disable_search`` only controls ``search-button-field`` (the full navbar
+   button showing the search label and keyboard shortcut) via
+   ``navbar_persistent``. It does not remove ``search-button`` (the icon-only
+   variant) or ``search-field.html`` if you have placed either of those
+   explicitly elsewhere in your layout. Remove them manually if needed.
+
+   If you set ``navbar_persistent`` explicitly in your ``html_theme_options``,
+   that value takes precedence and ``disable_search`` will not modify it.

src/pydata_sphinx_theme/__init__.py

@@ -48,6 +48,15 @@ def update_config(app):
             "a value (leave undefined), or set to an empty list."
         )
 
+    # If the user hasn't explicitly set navbar_persistent, default it based on
+    # disable_search: show the search button field unless search is disabled.
+    if "navbar_persistent" not in theme_options:
+        if theme_options.get("disable_search", False):
+            navbar_persistent = []
+        else:
+            navbar_persistent = ["search-button-field"]
+        theme_options["navbar_persistent"] = navbar_persistent
+
     # 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,14 +36,15 @@ logo =
 logo_link =
 surface_warnings = True
 back_to_top_button = True
+disable_search = False
 search_as_you_type = False
 shorten_urls = True
 
 # Template placement in theme layouts
 navbar_start = navbar-logo
 navbar_center = navbar-nav
 navbar_end = theme-switcher, navbar-icon-links
-navbar_persistent = search-button-field
+navbar_persistent =
 article_header_start = breadcrumbs
 article_header_end =
 article_footer_items =