Don't conflict with accessibility shortcuts.

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

docs/about/release-notes.md

@@ -238,6 +238,8 @@ value to the `theme.custom_dir` option and a warning was issued. As of version
 
 ### Other Changes and Additions to Version 1.0
 
+* Keyboard shortcuts changed to not conflict with commonly used accessibility
+  shortcuts (#1502.)
 * User friendly YAML parse errors (#1543).
 * Officially support Python 3.7.
 * A missing theme configuration file now raises an error.

docs/user-guide/styling-your-docs.md

@@ -26,8 +26,12 @@ the [Customizing a Theme][customize] section below.
 
 The default theme, which was built as a custom [Bootstrap] theme, supports most
 every feature of MkDocs. It only officially supports two levels in the
-navigation (see #1107). In addition to the default [theme configuration
-options], the `mkdocs` theme supports the following options:
+navigation (see #1107).
+
+![mkdocs](../img/mkdocs.png)
+
+In addition to the default [theme configuration options], the `mkdocs` theme
+supports the following options:
 
 * __`highlightjs`__: Enables highlighting of source code in code blocks using
   the [highlight.js] JavaScript library. Default: `True`.
@@ -35,16 +39,35 @@ options], the `mkdocs` theme supports the following options:
 * __`hljs_languages`__: By default, highlight.js only supports 23 common
   languages. List additional languages here to include support for them.
 
-```yaml
-theme:
-    name: mkdocs
-    highlightjs: true
-    hljs_languages:
-        - yaml
-        - rust
-```
+        theme:
+            name: mkdocs
+            highlightjs: true
+            hljs_languages:
+                - yaml
+                - rust
 
-![mkdocs](../img/mkdocs.png)
+* __`shortcuts`__: Defines keyboard shortcut keys.
+
+        theme:
+            name: mkdocs
+            shortcuts:
+                help: 191    # ?
+                next: 78     # n
+                previous: 80 # p
+                search: 83   # s
+
+    All values much be numeric key codes. It is best to use keys which are
+    available on all keyboards. You may use <http://keycode.info/> to determine
+    the key code for a given key.
+
+    * __`help`__: Display a help modal which lists the keyboard shortcuts.
+      Default: `191` (&quest;)
+
+    * __`next`__: Navigate to the "next" page. Default: `78` (n)
+
+    * __`previous`__: Navigate to the "previous" page. Default: `80` (p)
+
+    * __`search`__: Display the search modal. Default: `83` (s)
 
 ### readthedocs
 

mkdocs/tests/config/config_tests.py

@@ -130,7 +130,8 @@ class ConfigTests(unittest.TestCase):
                         'include_search_page': False,
                         'search_index_only': False,
                         'highlightjs': True,
-                        'hljs_languages': []
+                        'hljs_languages': [],
+                        'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
                     }
                 }, {
                     'dirs': [os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir],
@@ -172,7 +173,8 @@ class ConfigTests(unittest.TestCase):
                         'include_search_page': False,
                         'search_index_only': False,
                         'highlightjs': True,
-                        'hljs_languages': []
+                        'hljs_languages': [],
+                        'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
                     }
                 }
             )

mkdocs/tests/theme_tests.py

@@ -32,7 +32,8 @@ class ThemeTests(unittest.TestCase):
             'include_search_page': False,
             'search_index_only': False,
             'highlightjs': True,
-            'hljs_languages': []
+            'hljs_languages': [],
+            'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
         })
 
     def test_custom_dir(self):

mkdocs/themes/mkdocs/base.html

@@ -191,7 +191,10 @@
         </footer>
 
       {%- block scripts %}
-        <script>var base_url = '{{ base_url }}';</script>
+        <script>
+            var base_url = {{ base_url | tojson }},
+                shortcuts = {{ config.theme.shortcuts | tojson }};
+        </script>
         <script src="{{ 'js/base.js'|url }}" defer></script>
         {%- for path in config['extra_javascript'] %}
         <script src="{{ path|url }}" defer></script>

mkdocs/themes/mkdocs/js/base.js

@@ -35,25 +35,32 @@ $(document).ready(function() {
       }
     });
 
+    // Populate keyboard modal with proper Keys
+    $keyboard_modal.find('.help.shortcut kbd')[0].innerHTML = keyCodes[shortcuts.help];
+    $keyboard_modal.find('.prev.shortcut kbd')[0].innerHTML = keyCodes[shortcuts.previous];
+    $keyboard_modal.find('.next.shortcut kbd')[0].innerHTML = keyCodes[shortcuts.next];
+    $keyboard_modal.find('.search.shortcut kbd')[0].innerHTML = keyCodes[shortcuts.search];
+
     // Keyboard navigation
     document.addEventListener("keydown", function(e) {
         if ($(e.target).is(':input')) return true;
         var key = e.which || e.keyCode || window.event && window.event.keyCode;
         var page;
         switch (key) {
-            case 39:   // right arrow
+            case shortcuts.next:
                 page = $('[role="navigation"] a:contains(Next):first').prop('href');
                 break;
-            case 37:   // left arrow
+            case shortcuts.previous:
                 page = $('[role="navigation"] a:contains(Previous):first').prop('href');
                 break;
-            case 83:   // s
+            case shortcuts.search:
                 e.preventDefault();
                 $keyboard_modal.modal('hide');
                 $search_modal.modal('show');
                 $search_modal.find('#mkdocs-search-query').focus();
                 break;
-            case 191:  // ?
+            case shortcuts.help:
+                $search_modal.modal('hide');
                 $keyboard_modal.modal('show');
                 break;
             default: break;
@@ -91,3 +98,119 @@ $('body').scrollspy({
 $("li.disabled a").click(function() {
     event.preventDefault();
 });
+
+// See https://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes
+// We only list common keys below. Obscure keys are omited and their use is discouraged.
+var keyCodes = {
+  8: 'backspace',
+  9: 'tab',
+  13: 'enter',
+  16: 'shift',
+  17: 'ctrl',
+  18: 'alt',
+  19: 'pause/break',
+  20: 'caps lock',
+  27: 'escape',
+  32: 'spacebar',
+  33: 'page up',
+  34: 'page down',
+  35: 'end',
+  36: 'home',
+  37: '←',
+  38: '↑',
+  39: '→',
+  40: '↓',
+  45: 'insert',
+  46: 'delete',
+  48: '0',
+  49: '1',
+  50: '2',
+  51: '3',
+  52: '4',
+  53: '5',
+  54: '6',
+  55: '7',
+  56: '8',
+  57: '9',
+  65: 'a',
+  66: 'b',
+  67: 'c',
+  68: 'd',
+  69: 'e',
+  70: 'f',
+  71: 'g',
+  72: 'h',
+  73: 'i',
+  74: 'j',
+  75: 'k',
+  76: 'l',
+  77: 'm',
+  78: 'n',
+  79: 'o',
+  80: 'p',
+  81: 'q',
+  82: 'r',
+  83: 's',
+  84: 't',
+  85: 'u',
+  86: 'v',
+  87: 'w',
+  88: 'x',
+  89: 'y',
+  90: 'z',
+  91: 'Left Windows Key / Left ⌘',
+  92: 'Right Windows Key',
+  93: 'Windows Menu / Right ⌘',
+  96: 'numpad 0',
+  97: 'numpad 1',
+  98: 'numpad 2',
+  99: 'numpad 3',
+  100: 'numpad 4',
+  101: 'numpad 5',
+  102: 'numpad 6',
+  103: 'numpad 7',
+  104: 'numpad 8',
+  105: 'numpad 9',
+  106: 'multiply',
+  107: 'add',
+  109: 'subtract',
+  110: 'decimal point',
+  111: 'divide',
+  112: 'f1',
+  113: 'f2',
+  114: 'f3',
+  115: 'f4',
+  116: 'f5',
+  117: 'f6',
+  118: 'f7',
+  119: 'f8',
+  120: 'f9',
+  121: 'f10',
+  122: 'f11',
+  123: 'f12',
+  124: 'f13',
+  125: 'f14',
+  126: 'f15',
+  127: 'f16',
+  128: 'f17',
+  129: 'f18',
+  130: 'f19',
+  131: 'f20',
+  132: 'f21',
+  133: 'f22',
+  134: 'f23',
+  135: 'f24',
+  144: 'num lock',
+  145: 'scroll lock',
+  186: ';',
+  187: '=',
+  188: ',',
+  189: '‐',
+  190: '.',
+  191: '?',
+  192: '`',
+  219: '[',
+  220: '\',
+  221: ']',
+  222: ''',
+};

mkdocs/themes/mkdocs/keyboard-modal.html

@@ -15,19 +15,19 @@
                 </thead>
                 <tbody>
                   <tr>
-                    <td><kbd>?</kbd></td>
+                    <td class="help shortcut"><kbd>?</kbd></td>
                     <td>Open this help</td>
                   </tr>
                   <tr>
-                    <td><kbd>&larr;</kbd></td>
-                    <td>Previous page</td>
-                  </tr>
-                  <tr>
-                    <td><kbd>&rarr;</kbd></td>
+                    <td class="next shortcut"><kbd>n</kbd></td>
                     <td>Next page</td>
                   </tr>
                   <tr>
-                    <td><kbd>s</kbd></td>
+                    <td class="prev shortcut"><kbd>p</kbd></td>
+                    <td>Previous page</td>
+                  </tr>
+                  <tr>
+                    <td class="search shortcut"><kbd>s</kbd></td>
                     <td>Search</td>
                   </tr>
                 </tbody>
@@ -38,4 +38,3 @@
         </div>
     </div>
 </div>
-

mkdocs/themes/mkdocs/mkdocs_theme.yml

@@ -8,3 +8,9 @@ search_index_only: false
 
 highlightjs: true
 hljs_languages: []
+
+shortcuts:
+    help: 191    # ?
+    next: 78     # n
+    previous: 80 # p
+    search: 83   # s

mkdocs/themes/readthedocs/js/theme.js

@@ -17,10 +17,10 @@ $( document ).ready(function() {
         var key = e.which || e.keyCode || window.event && window.event.keyCode;
         var page;
         switch (key) {
-            case 39:  // right arrow
+            case 78:  // n
                 page = $('[role="navigation"] a:contains(Next):first').prop('href');
                 break;
-            case 37:  // left arrow
+            case 80:  // p
                 page = $('[role="navigation"] a:contains(Previous):first').prop('href');
                 break;
             default: break;