ENH: create a navbar_persistent section

docs/conf.py

@@ -136,12 +136,12 @@
     "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     "navbar_center": ["version-switcher", "navbar-nav"],
     "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
-    # "announcement": "Here's a test <a href='https://google.com'>announcement</a>!",
     # "show_nav_level": 2,
     # "navbar_start": ["navbar-logo"],
-    # "navbar_end": ["theme-switcher", "navbar-icon-links"],  # Just for testing, we should use defaults in our docs
+    # "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    # "navbar_persistent": ["search-button"],
     # "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
-    # "footer_items": ["copyright", "sphinx-version", ""],
+    # "footer_items": ["copyright", "sphinx-version"],
     # "secondary_sidebar_items": ["page-toc.html"],  # Remove the source buttons
     "switcher": {
         "json_url": json_url,

docs/user_guide/layout.rst

@@ -204,6 +204,7 @@ Each section is configured in ``conf.py`` with the following configuration:
 - Left section: ``html_theme_options['navbar_start']``
 - Middle menu: ``html_theme_options['navbar_center']``
 - Right section: ``html_theme_options['navbar_end']``
+- Persistent right section: ``html_theme_options['navbar_persistent']``
 
 By default, the following configuration is used:
 
@@ -213,10 +214,15 @@ By default, the following configuration is used:
    ...
    "navbar_start": ["navbar-logo"],
    "navbar_center": ["navbar-nav"],
-   "navbar_end": ["navbar-icon-links"]
+   "navbar_end": ["navbar-icon-links"],
+   "navbar_persistent": ["search-button"]
    ...
    }
 
+.. warning::
+
+    The *Persistent right section* is placed next to the ``navbar_end`` but its elements will remain visible in the header even on small screens when all other elements are collapsed. It has been design for the ``search-button`` only and we cannot guarantee its compatibility with other components.
+
 Configure the navbar center alignment
 -------------------------------------
 

docs/user_guide/search.rst

@@ -14,7 +14,7 @@ You can also configure some aspects of the search button and search field, descr
 Configure the search field position
 -----------------------------------
 
-The position of the search *button* is controlled by ``search-button`` and by default is included in ``html_theme_options["navbar_end"]``; you may move it elsewhere as befits your site's layout, or remove it. You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_items"]``, etc).
+The position of the search *button* is controlled by ``search-button`` and by default is included in ``html_theme_options["navbar_persistent"]``; you may move it elsewhere as befits your site's layout, or remove it. You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_items"]``, etc).
 
 For example, if you'd like the search field to be in your side-bar, add it to
 the sidebar templates like so:

src/pydata_sphinx_theme/__init__.py

@@ -176,6 +176,7 @@ def update_templates(app, pagename, templatename, context, doctree):
     template_sections = [
         "theme_navbar_start",
         "theme_navbar_center",
+        "theme_navbar_persistent",
         "theme_navbar_end",
         "theme_footer_items",
         "theme_secondary_sidebar_items",

src/pydata_sphinx_theme/assets/styles/components/_search.scss

@@ -118,23 +118,3 @@
     font-size: var(--pst-font-size-icon);
   }
 }
-
-/**
- * Button behavior on mobile / wide so it shows up in the header on mobile.
- */
-
-// The navbar end version should only show on wide screens
-.navbar-end__search-button-container {
-  display: none;
-  @include media-breakpoint-up($breakpoint-sidebar-primary) {
-    display: flex;
-  }
-}
-
-// The one next to the hamburger menu only shows on narrow screens
-.search-button-container--mobile {
-  margin-left: auto;
-  @include media-breakpoint-up($breakpoint-sidebar-primary) {
-    display: none;
-  }
-}

src/pydata_sphinx_theme/assets/styles/sections/_header.scss

@@ -174,3 +174,19 @@
     }
   }
 }
+
+// THe elements next to the hamburger menu only show on narrow screens
+.navbar-persistent--mobile {
+  margin-left: auto;
+  @include media-breakpoint-up($breakpoint-sidebar-primary) {
+    display: none;
+  }
+}
+
+// The navbar-persistent content should only show on wide screens
+.navbar-persistent--container {
+  display: none;
+  @include media-breakpoint-up($breakpoint-sidebar-primary) {
+    display: flex;
+  }
+}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html

@@ -19,9 +19,11 @@
     </div>
 
     <div id="navbar-end">
-      <div class="navbar-end-item navbar-end__search-button-container">
-        {% include "../components/search-button.html" %}
-      </div>
+      {% for navbar_item in theme_navbar_persistent %}
+        <div class="navbar-end-item navbar-persistent--container">
+          {% include navbar_item %}
+        </div>
+      {% endfor %}
       {% for navbar_item in theme_navbar_end %}
       <div class="navbar-end-item">
         {% include navbar_item %}
@@ -32,9 +34,11 @@
 
 
   {# A search button to show up only on mobile #}
-  <div class="search-button-container--mobile">
-    {%- include "../components/search-button.html" %}
-  </div>
+  {% for navbar_item in theme_navbar_persistent %}
+    <div class="navbar-persistent--mobile">
+      {%- include navbar_item %}
+    </div>
+  {% endfor %}
 
   {% if not remove_sidebar_secondary %}
   <label class="sidebar-toggle secondary-toggle" for="__secondary">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -31,6 +31,7 @@ navbar_align = content
 navbar_start = navbar-logo.html
 navbar_center = navbar-nav.html
 navbar_end = theme-switcher.html, navbar-icon-links.html
+navbar_persistent = search-button.html
 header_links_before_dropdown = 5
 primary_sidebar_end = sidebar-ethical-ads.html
 footer_items = copyright.html, theme-version.html, sphinx-version.html