From 09d9c438b7a9c6f3a33e3a5c4fd5cbda3d273f4a Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Thu, 19 Sep 2024 13:41:06 -0700 Subject: [PATCH] docs: Fix search UI description Updates the search doc in the user guide to describe the default search UI on both narrow and wide viewports. Also breaks all lines in the doc at 80-characters width. Fix: #1781 --- docs/user_guide/search.rst | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/user_guide/search.rst b/docs/user_guide/search.rst index ecab78254..82302349f 100644 --- a/docs/user_guide/search.rst +++ b/docs/user_guide/search.rst @@ -2,20 +2,25 @@ Search bar / search button ========================== -By default, the search input field is hidden, and there is a search button -(a magnifying glass icon :fas:`search`) in the top navbar. -The search input field will be displayed when a user either: +On narrow viewports, users can access search by clicking the magnifying glass +icon (:fas:`search`) in the :ref:`layout-header`. On wide viewports, the +magnifying glass icon, search input field, and keyboard shortcut for focusing +the search input field are all shown. The default keyboard shortcut is: -- Clicks the search button in the header. -- Presses the keyboard shortcut :kbd:`Ctrl` + :kbd:`K` (Linux, Windows) or :kbd:`⌘` + :kbd:`K` (macOS). +* :kbd:`Ctrl` + :kbd:`K` (Linux, Windows) +* :kbd:`⌘` + :kbd:`K` (macOS) You can also configure some aspects of the search button and search field, described below. 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_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_start"]``, 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_start"]``, etc.). For example, if you'd like the search field to be in your sidebar, add it to the sidebar templates like so: @@ -37,7 +42,14 @@ following configuration: .. warning:: - If a page includes *both* the search button and an always-visible search field, the keyboard shortcuts will focus on the always-visible field and the hidden search field overlay will not display. *This may not be what you want:* on small screens (i.e. mobile devices) the sidebars may be hidden in a drawer, and if the persistent search field is there, it may receive focus without actually being made visible. It is **strongly recommended** that you use *either* the search button and the hidden/overlaid field that comes with it, *or* use a persistent search field in a place that makes sense for your layout. + If a page includes *both* the search button and an always-visible search + field, the keyboard shortcuts will focus on the always-visible field and the + hidden search field overlay will not display. *This may not be what you want:* + on small screens (i.e. mobile devices) the sidebars may be hidden in a drawer, + and if the persistent search field is there, it may receive focus without + actually being made visible. It is **strongly recommended** that you use + *either* the search button and the hidden/overlaid field that comes with it, + *or* use a persistent search field in a place that makes sense for your layout. Configure the search bar text