Skip to content
/ mkdocs Public
  • Sponsor
  • Notifications You must be signed in to change notification settings
  • Fork 2.5k
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change keyboard navigation keys #1502

Closed
pols12 opened this issue Jun 5, 2018 · 5 comments
Closed

Change keyboard navigation keys #1502

pols12 opened this issue Jun 5, 2018 · 5 comments
Labels
Needs design decision Theme-general Issues involving the theme related code within MkDocs
Milestone

Comments

@pols12
Copy link

pols12 commented Jun 5, 2018

Hi!

I have enabled “Always use the cursor keys to navigate within pages” (Accessibility option) in my Firefox, in order to easily navigate in text content, copy, paste, see overflowing text…

However since #1095, I cannot use arrow keys in these purpose any more. That’s why it would be nice to change the attached shortcuts.

However, I know I’m a rare user to have this issue, I would understand a WONTFIX status.

@waylan
Copy link
Member

waylan commented Jun 5, 2018

While I'm certainly sympathetic to supporting accessibility options, we discussed the shortcuts pretty extensively in #1095 and ultimately decided to copy Sphinx shortcuts. Sphinx has a much larger user base than MkDocs, so if this is an issue, I'm curios why they haven't encountered it (maybe they have, I haven't searched there project).

I guess my question is: is the Firefox option a common paradigm or unique to Firefox only? If it is common across multiple platforms, then we shouldn't interfere with it. However, if it is simply some experimental one-off, then I'm not so sure we need to do anything.

@pols12
Copy link
Author

pols12 commented Jun 5, 2018

There is no accessibility feature in Chromium core, but official accessibility plug-ins include Keyboard Navigation by Google Accesibility.

@waylan
Copy link
Member

waylan commented Jun 5, 2018

Interesting, but I also can find multiple plugins which use Vim shortcuts for the same features. The problem is that whichever set of keys we use, we are likely to break someones preferred shortcuts. That said, accessibility is more important than user preferences. So, for example, if we use vim shortcuts and that interferes with a user's vim plugin, we can say we had to use those shortcuts so we didn't break accessibility. But the real question is, which set of shortcuts should we use?

@waylan
Copy link
Member

waylan commented Jun 5, 2018

As an aside, the keyboard shortcuts are theme specific. You may find some third party themes that use different shortcuts (or none at all). Some themes might even make them configurable. That said, the default (builtin) themes should follow best practices.

@waylan waylan added this to the 1.0.0 milestone Jun 20, 2018
@waylan waylan added the Theme-general Issues involving the theme related code within MkDocs label Jul 6, 2018
@waylan
Copy link
Member

waylan commented Jul 12, 2018

Here is my proposal to resolve this issue:

  1. Use n/p for next/previous by default.
  2. Add theme specific settings (theme.shortcuts.next, ect) to allow users to override the defaults.

While n/p is very English-centric, it matches our use of s for search. And by making it customizable, a project in another language can change the defaults to whatever makes sense in their language. If a user really wants to use the arrow keys and disregard the accessibility conflict, they can. And by using theme specific settings, we are not adding any more settings to MkDocs itself.

The one concern I have it how to designate the key codes in the settings. The JavaScript code which acts on the keypresses requires the numeric key code which does not change for a given key regardless of keyboard layout. But users may not always know what the key codes are. We could point people to http://keycode.info/ to get the key codes for them to enter as values to the settings. or we could allow chars as values and try to convert to a keycode. Not sure how reliable or easy that conversion is for different keyboard layouts though (looks to not be straightforward -- read the comments as the "accepted" answer is apparently wrong).

waylan added a commit to waylan/mkdocs that referenced this issue Jul 13, 2018
In both built-in themes, the default next/prev shortcut keys were 
changed from arrows to n/p as the arrows conflict with common browser 
accessibility extensions.

In the mkdocs theme,  users can now configure the shortcuts to whatever 
they want. Note that these config options are theme specific. The 
readthedocs theme does not get these options as they are not available 
on the parent theme.

Fixes mkdocs#1502
waylan added a commit to waylan/mkdocs that referenced this issue Jul 13, 2018
In both built-in themes, the default next/prev shortcut keys were
changed from arrows to n/p as the arrows conflict with common browser
accessibility extensions.

In the mkdocs theme,  users can now configure the shortcuts to whatever
they want. Note that these config options are theme specific. The
readthedocs theme does not get these options as they are not available
on the parent theme.

Fixes mkdocs#1502
waylan added a commit that referenced this issue Jul 13, 2018
In both built-in themes, the default next/prev shortcut keys were
changed from arrows to n/p as the arrows conflict with common browser
accessibility extensions.

In the mkdocs theme,  users can now configure the shortcuts to whatever
they want. Note that these config options are theme specific. The
readthedocs theme does not get these options as they are not available
on the parent theme.

Fixes #1502
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Needs design decision Theme-general Issues involving the theme related code within MkDocs
Projects
None yet
Development

No branches or pull requests

2 participants