diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index a78859ca..eb996f51 100644 --- a/docs/about/release-notes.md +++ b/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. diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 1663e006..b485b5b1 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/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 to determine + the key code for a given key. + + * __`help`__: Display a help modal which lists the keyboard shortcuts. + Default: `191` (?) + + * __`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 diff --git a/mkdocs/tests/config/config_tests.py b/mkdocs/tests/config/config_tests.py index 4e224173..8f5fe08d 100644 --- a/mkdocs/tests/config/config_tests.py +++ b/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} } } ) diff --git a/mkdocs/tests/theme_tests.py b/mkdocs/tests/theme_tests.py index d06b3c15..39e32a07 100644 --- a/mkdocs/tests/theme_tests.py +++ b/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): diff --git a/mkdocs/themes/mkdocs/base.html b/mkdocs/themes/mkdocs/base.html index 5b4854ac..a8fef736 100644 --- a/mkdocs/themes/mkdocs/base.html +++ b/mkdocs/themes/mkdocs/base.html @@ -191,7 +191,10 @@ {%- block scripts %} - + {%- for path in config['extra_javascript'] %} diff --git a/mkdocs/themes/mkdocs/js/base.js b/mkdocs/themes/mkdocs/js/base.js index b7cd6a68..4755f434 100644 --- a/mkdocs/themes/mkdocs/js/base.js +++ b/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: ''', +}; diff --git a/mkdocs/themes/mkdocs/keyboard-modal.html b/mkdocs/themes/mkdocs/keyboard-modal.html index f903ddf8..eb9e09c8 100644 --- a/mkdocs/themes/mkdocs/keyboard-modal.html +++ b/mkdocs/themes/mkdocs/keyboard-modal.html @@ -15,19 +15,19 @@ - ? + ? Open this help - ← - Previous page - - - → + n Next page - s + p + Previous page + + + s Search @@ -38,4 +38,3 @@ - diff --git a/mkdocs/themes/mkdocs/mkdocs_theme.yml b/mkdocs/themes/mkdocs/mkdocs_theme.yml index 5ba0caa5..d6109c23 100644 --- a/mkdocs/themes/mkdocs/mkdocs_theme.yml +++ b/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 diff --git a/mkdocs/themes/readthedocs/js/theme.js b/mkdocs/themes/readthedocs/js/theme.js index 1a30ccea..c3801dc4 100644 --- a/mkdocs/themes/readthedocs/js/theme.js +++ b/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;