Add configurable keyboard shortcut to focus search input (#1411)

Adds a keyboard shortcut to use Ctrl/Cmd and a configurable key to focus the search input. The key is configurable with `search.focus_shortcut_key`; enables it on the core docs site with `'k'` (default on many sites).

---------
Co-authored-by: Matt Wang <mxw@cs.washington.edu>

CHANGELOG.md

@@ -17,6 +17,7 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
+- Added: configurable keyboard shortcut to focus search input by [@kcromanpl-bajra] in [#1411]
 - Fixed: incorrect navigation when `.html` omitted from URL by [@pdmosses] in [#1374]
 - Fixed: incorrect positioning of clickable area for navigation links on Safari by [@mattxwang] in [#1403]
 
@@ -29,10 +30,12 @@ Docs changes made since the latest release:
 - [@mitchnemirov] made their first contribution in [#1390]
 
 [@mitchnemirov]: https://github.com/mitchnemirov
+[@kcromanpl-bajra]: https://github.com/kcromanpl-bajra
 
 [#1374]: https://github.com/just-the-docs/just-the-docs/pull/1374
 [#1390]: https://github.com/just-the-docs/just-the-docs/pull/1390
 [#1403]: https://github.com/just-the-docs/just-the-docs/pull/1403
+[#1411]: https://github.com/just-the-docs/just-the-docs/pull/1411
 
 ## Release v0.7.0
 

_config.yml

@@ -78,6 +78,8 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 
 # For copy button on code
 enable_copy_code_button: true

assets/js/just-the-docs.js

@@ -145,6 +145,18 @@ function searchLoaded(index, docs) {
   var currentInput;
   var currentSearchIndex = 0;
 
+  {%- if site.search.focus_shortcut_key %}
+  // add event listener on ctrl + <focus_shortcut_key> for showing the search input
+  jtd.addEvent(document, 'keydown', function (e) {
+    if ((e.ctrlKey || e.metaKey) && e.key === '{{ site.search.focus_shortcut_key }}') {
+      e.preventDefault();
+
+      mainHeader.classList.add('nav-open');
+      searchInput.focus();
+    }
+  });
+  {%- endif %}
+
   function showSearch() {
     document.documentElement.classList.add('search-active');
   }
@@ -488,7 +500,7 @@ jtd.setTheme = function(theme) {
 
 function navLink() {
   var pathname = document.location.pathname;
-  
+
   var navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"]');
   if (navLink) {
     return navLink;

docs/configuration.md

@@ -66,6 +66,8 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 ```
 
 ## Mermaid Diagrams

docs/search.md

@@ -94,6 +94,21 @@ The search button displays in the bottom right corner of the screen and triggers
 search.button: true
 ```
 
+### Focus search bar with a keyboard shortcut
+
+Just the Docs supports focusing the search bar input with a keyboard shortcut. After setting the `search.focus_shortcut_key` config item key, users who press <kbd>Ctrl</kbd> + `search.focus_shortcut_key` (or on macOS, <kbd>Command</kbd> + `search.focus_shortcut_key`) will focus the search bar.
+
+Note that this feature is **disabled by default**. `search.focus_shortcut_key` should be a [valid value from `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key); this involves all ASCII alphanumeric values, as well as modifier keys.
+
+For example,
+
+```yaml
+search:
+    focus_shortcut_key: 'k'
+```
+
+Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users (and <kbd>Command</kbd> + <kbd>K</kbd> on macOS).
+
 ## Hiding pages from search
 
 Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page.