Feature: navigation keyboard bindings/shortcuts

[jhildenbiddle]

Feature request

Improve accessibility by implementing keyboard bindings/shortcuts for common navigation actions.

Linked PR: #2279

Proposal

Provide the following navigation keyboard bindings/shortcuts for all docsify sites by default:

1. Toggle the sidebar menu
2. Move focus on the main content area
3. Move focus to the search field (and toggle sidebar if necessary)

Because all three of the above shortcuts are associated with DOM elements, keyboard binding hints can be provided to the user by hovering (via title attribute) or focusing (via aria-keyshortcuts attribute) on each associated element (sidebar toggle button, the "Skip to main content" element from #2253, and the search input field).

Optional

Allow custom keyboard binding functions to be defined as part of the docsify configuration. Docsify will handle capturing these keyboard shortcuts and invoking the associated function.

Example Implementation

window.$docsify = {
  keyBindings: {
    // Example: Docsify default shortcut
    'toggleSidebar': {
      binding: 'alt+t',
      label: 'Toggle sidebar menu',
      callback(e) {
          const toggleElm = document.querySelector('.sidebar-toggle');

          if (toggleElm) {
            toggleElm.click();
            toggleElm.focus();
          }
      },
    },
    // Example: Plugin custom shortcut
    'myPlugin': {
      binding: 'alt+ctrl+shift+meta+a',
      label: 'Do a plugin thing',
      callback(e) {
        // ...
      },
    },
  }
}

Disable key bindings:

window.$docsify = {
  keyBindings: false,
}

Links

• https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts

[trusktr]

I've implemented this recently in an app. Custom key bindings don't need to be Docsify specific, and it can be a standalone library.

Docsify could have its own bindings made with it, and we can turn it on/off, but if someone want their own bindings they just use the lib:

import {Actions} from 'foo-actions-lib'

new Actions({
  target: document, // default
  actions: {
    // ... similar type of config object ...
  }
})

And then if users want to map actions to Docsify functions, they can call docsifyInstance.openMenu(), closeMenu(), etc

If we implement it that way, we could the decide if it is really worth adding a $docsify config for actions, which would itself just be a tiny plugin to pass it along to a new Actions.

---

Also I'd like to abstract Docsify's layout into templates that can be swapped out. Perhaps a totally different menu system in a new template would have its own key bindings, so this could be a feature specific to each eventual template, unless we restrict the template system to always accepting only content, sidebar, and menu replacements, then we control them all the same way.

<docsify-app>
  <my-sidebar slot="sidebar"></my-sidebar>
  <my-body slot="content"></my-body>
  <!-- etc -->
</docsify-app>

Where each slotted element receives the content to render for each part of the site. Or fully replaced:

<docsify-app replace="my-full-template"></docsify-app>

where it accepts a custom element to fully replace the template with, or something (just random ideas at this point, but the idea is making alternative Docsify themes possible (not just CSS themes, but alternative DOM too)).

Hard to tell exactly how both of these ideas play well together ATM.

---

Do you have examples of this in other doc sites?

[jhildenbiddle]

Appreciate the feedback, @trusktr. I'm not sure I'm following though. Hopefully what follows will help clarify...

I think there are two main questions to be answered:

1. Should Docsify provide keyboard shortcuts for site visitors? If so, which ones?
2. Should Docsify provide the ability to create custom keyboard shortcuts?

In hindsight perhaps it would have been better to submit these as separate feature requests. I didn't do that because they are closely related and I was in an implementation mindset while creating a draft PR for this issue (#2279). I will split these into separate issues if needed.

---

1. Should Docsify provide keyboard shortcuts for site visitors?

I believe the answer is "yes". I view this as a non-controversial feature that aligns with other accessibility-related Docsify work being done (#2253, #2254, #2264, #2265, #2269).

Keyboard shortcuts improve accessibility for users navigating sites with a keyboard and/or assistive devices. Many popular websites offer them:

• Facebook (details)
• Twitter (details)
• YouTube (details)
• Jira (details)
• Trello (details)
• GitHub (details)
• Reddit (press ? for shortcut menu)

Other documentation generators like GitBook, Docusaurus, Starlight, and VuePress offer a keyboard shortcut for the search field. These sites, like Docsify, would also benefit from additional shortcuts like the ones I've proposed above. Try navigating between pages on any of these sites using just the keyboard and this will quickly become apparent.

Most people are unaware that these shortcuts exist on popular websites because most people do not navigate websites primarily with a keyboard or assistive device. For those who do, these shortcuts can dramatically improve the efficiency with which they navigate and perform common tasks.

---

2. Should Docsify provide the ability to create custom keyboard shortcuts?

This is where I believe further discussion is warranted.

My initial thoughts were that this would be useful mostly for plugin authors. Standardizing and simplifying keyboard shortcut implementations offers many benefits over requiring plugin authors to implement their own potentially problematic implementations:

• Simplified DX
• Less code sent over the wire, to test, and to maintain
• Reduced risk of implementation conflicts/issues

Having all shortcuts registered with Docsify also provides UX enhancement opportunities for site owners and visitors. For example, this would allow Docsify to generate a keyboard shortcut menu similar to the one seen on Reddit (displayed using the ? keyboard shortcut):

Remember, site owners and plugin authors who prefer to implement their own shortcut handling logic will always be free to do so. The goal with providing custom keyboard shortcuts via the Docsify configuration is to simplify the process of implementing keyboard shortcuts so that we can improve the Docsify developer and user experience.

FWIW, Docusaurus has an open RFC for something similar. It hasn't seen much activity since 2021, but I wanted to share it to demonstrate that others have had similar ideas and believed it would be useful.

---

Ping: @paulhibbitts, @kburk1997, @andrapetronela for accessibility-focused feedback.

[paulhibbitts]

Thanks for the issue/ping @jhildenbiddle and sharing your thoughts @trusktr ! While I do not have any specific accessibility-focused feedback (I am learning more as I go...) the recent accessibility PR's of @jhildenbiddle have highlighted to me as well the importance of keyboard shortcuts in relation to making Docsify more accessible for everyone. Additional default keyboard shortcuts would be a valuable addition for me, esp. my audience of open educators/publishers.

[vhscom]

This was closed as completed in #2279. Should the keyboard accessibility features added be available on docsify.js.org? Currently, when I press keyboard keys / or Cmd/Ctrl + K on the Docsify docs site nothing happens.

[jhildenbiddle]

@vhscom --

The work has been completed but not yet released. You can review the feature via the docsify develop branch preview.