1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
|
Search bar / search button
==========================
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 keyboard shortcut is:
* :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.).
For example, if you'd like the search field to be in your sidebar, add it to
the sidebar templates like so:
.. code:: python
html_sidebars = {
"**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
}
If instead, you'd like to put the search field in the top navbar, use the
following configuration:
.. code:: python
html_theme_options = {
"navbar_end": ["navbar-icon-links.html", "search-field.html"]
}
.. 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.
Configure the search bar text
-----------------------------
To modify the text that is in the search bar before people click on it, add the
following configuration to your ``conf.py`` file:
.. code:: python
html_theme_options = {
"search_bar_text": "Your text here..."
}
|
