Add keyboard navigation #1095

mreinhardt · 2016-11-17T02:00:03Z

Right arrow or n for next page. Left arrow or p for previous page. Disabled when cursor is in an input element.

waylan · 2016-11-17T16:31:23Z

This is a nice feature to have. Thanks for the contribution.

I noticed that both the n/p and the right and left arrow keys are used for navigation. Just did a quick search and the discussion at sphinx-doc/sphinx#2064 is interesting. Sphinx appears to only be using the arrow keys. Is there any president to also using n/p? And their discussion includes a concern that using the arrow keys might break normal left/right scrolling in the browser. They decided to go forward anyway and neither their themes nor ours should have any left/right scrolling anyway. Just wanted to make sure we are aware of the issues involved.

Finally, I appears that the pypy3 tests failed (on Travis) due to an error creating the envs. I restarted them, but the outcome was the same. In any even, the problem does not appear to be related to this PR. Even more curious is that the appveyor tests were never even triggered. Again, it does not appear to be an issue with this PR, but we may have some new issues with our automation setup. Sigh.

mreinhardt · 2016-11-17T17:16:45Z

I can remove the n/p. I thought about [/] also. We could mitigate the arrow/horiz-scroll issue by using either of these instead, but like you said it doesn't seem to matter in our case unless someone made a wacky theme.

No idea about the Travis failure, it's only a little JS!

waylan · 2016-11-17T18:41:48Z

I can remove the n/p. I thought about [/] also.

I would prefer we use whatever is common. Other than my quick search which tuned up what Sphinx does, I have no idea what other projects use for this use case.

In my experience, many apps us j/k (from vim for next/previous line), but they correspond with the up/down arrow keys rather than right/left (for example navigating to the next/previous email which are usually in a vertical list). Still might be the least surprising to people who actually use keyboard shortcuts regularly. There is a pretty comprehensive list of keyboard shortcuts across multiple platforms on Wikipedia, but nothing else stands out to me as a good fit.

waylan · 2016-11-17T19:05:31Z

I should add that n/p is very English specific. They could be different for every language.

In contrast, the vim shortcuts apparently come from the ADM-3A keyboard layout, where the ←↓↑→ keys corresponded with the HJKL keys (in that order) not because of any meaning implied by the letters, but because if their location on the keyboard (see image). By that metric, we should use h/l for previous/next respecitively. And the proper way to code that would be to use the key codes for those specific keys even if the user has their keyboard mapped to different letters (ex: Dvorak or non-English).

Regardless, I think it makes sense to leave the arrow keys support as it is now.

mreinhardt · 2016-11-17T19:24:27Z

Another option is that arrows could be default with a setting in mkdocs.yml to override this behavior, and even disable keyboard shortcuts entirely. Would take a lot more code for this but I can tackle it if you think it's necessary.

mreinhardt · 2016-11-17T19:28:58Z

BTW - Gmail uses n/p for "Read previous/next message", but I understand why that's not the best option here.

waylan · 2016-11-17T19:41:51Z

Let's not add any more settings.

Really, Gmail uses n/p? Way back when they first introduced keyboard shortcuts I thought they used j/k. But I haven't used Gmail in years. Maybe that's too nerdy/geeky/[insert appropriate adjective here] for the average user?

mreinhardt · 2016-11-17T19:45:07Z

Yes, vimmy j/k for next/prev email thread, n/p is for next/prev message in a thread.

waylan · 2016-11-17T20:02:38Z

Okay, I see three options:

Follow Sphinx's lead and use arrows only.
Use a bunch of shortcuts for each action. Perhaps ←/h/p for "previous" and →/l/n for "next". That way, whatever the user tries will be likely to work. We could even throw j/k in there.
Pick a sensible single set of shortcuts and create a popup modal (using the existing bootswatch tools) which documents them. Maybe the model displays on the ? shortcut. We could then add a few others to focus the search box, etc. This would only work for bootswatch/bootstrap themes though, so readthedocs is out.

I'm partial to 1 or 3 but would be willing to accept whichever one gets built.

mreinhardt · 2016-11-17T20:05:11Z

3 seems best to me. I don't understand why it wouldn't work on readthedocs though, easy enough to make a little modal with some basic vanilla CSS/JS.

d0ugal · 2016-11-17T21:12:30Z

1 or 3 is fine. Maybe even 1 now as it is easy then 3 later.

mreinhardt · 2016-11-18T14:56:18Z

@waylan @d0ugal I amended the commit with the changes discussed.

waylan · 2016-11-18T15:58:29Z

@mreinhardt Wow. Looks good at a glance. I'll take a closer look later.

However, you are getting a few minor csslint failures. You can ignore the other (pypy3) failures as they are not related to this PR.

mreinhardt · 2016-11-18T17:41:54Z

@waylan Installed tox and csslint and fixed issues.

mreinhardt · 2016-11-21T22:27:21Z

I know it's unrelated, but is there anything I can do to help fix the other tests?

waylan · 2016-11-22T03:16:10Z

The other failures appears to be an incompatibility between the latest version of pip (or one of its dependencies) and pypy3. The failure is happening in environment creation, long before our tests are run. Not sure what can be done about that as we don't get to pick which version of pip gets installed in each environment (at least I'm not aware of a way). Hopefully either pip or pypy3 will get a quick update which resolves the problem. Otherwise, I'm not sure what the best approach is here.

In any event, sorry but I just haven't had time to look closely at your changes in this PR yet. Hopefully I'll get to it sometime this week.

waylan · 2016-11-23T15:39:36Z

I took a closer look and overall I think this looks good. However, there are a couple minor issues.

First of all the table in the modal needs adjusted in the readthedocs theme (its fine in the mkdocs theme). It should probably stretch to fill the modal or the modal should shrink to the size of the table. This is a nitpick, but we might as well get it right.

The other issue is a little more of a problem. The modal works fine except when you use one of the shortcuts before closing the modal (yes, the normal ways of closing the modal works such as the esc key, clicking the close button or clicking elsewhere on the page). For example, if you open the modal, then press the search shortcut (Alt-s), the modal does not close, but the search shortcut is followed. Here is an example in the readthedocs theme:

As you can see, I've started to type a search term and the browser's history feature also shows a dropdown of past search terms. It would be preferable if the modal had closed when I hit the shortcut.

However, even more concerning is the mkdocs theme:

In that case, the search modal appears behind the shortcut modal (the darkened background actually doubles in darkness). And even stranger, the search box has focus and you can type a search term and get results (and the browser shows search history), all while the search modal is hidden behind the shortcut modal. If you use the normal methods for closing the shortcut modal, then the search modal is properly visible. This is clearly a broken user interface. I could live with the other issues, but this needs to be fixed.

I will add that the other shortcuts are not an issue as the navigation shortcuts load another page and the modal gets reset anyway.

I see a few possible solutions:

Close the modal on any key-press. However, we only need to be listening for key-presses when it is open, so I'm not sure this is the right solution.
Close the modal (if it is open) as the first action of any keyboard shortcut. Of course, this would mean that only the shortcut keys would close it, not any key.
Disable the shortcuts when any modal is open, which more closely matches the behavior of the modal in other respects (scrolling is disabled, you can only tab through the modal elements, etc). The user would need to close the modal before using a shortcut.

I think option 3 probably makes the most sense. AFAICT, this is the behavior used by GMail. And perhaps we should list esc as a shortcut to close the modal.

Finally, the up/down arrow keys do nothing in the mkdocs theme when a modal is open (which is normal behavior) but still scroll the page behind the modal in the readthedocs theme. Also in the readthedocs theme you can tab through the entire page, but only through the modal elements in the mkdocs theme. This inconsistency should be fixed as well.

waylan · 2016-11-23T16:14:32Z

Something keeps bothering me about this. The readthedocs theme is intended to be a clone of the Sphinx theme by the same name. Thus far, the only differences are due to low level differences between MkDocs and Sphinx. Adding a modal feels like a little too much of a departure from that. Perhaps we should only use the modal in the mkdocs theme and in the readthedocs theme simply clone Sphinx shortcuts (right and left arrows), but offer nothing more.

A bonus is that we would not need to develop and maintain a complete modal system for the readthedocs theme. I, for one, am not really interested in maintaining that long-term. Disabling scrolling/tab etc, and other work to match the bootswatch modal would not be needed then.

mreinhardt · 2016-11-23T19:32:18Z

@waylan Sounds good. Will only use ←/→ on readthedocs theme, and will implement "Close the modal (if it is open) as the first action of any keyboard shortcut. Of course, this would mean that only the shortcut keys would close it, not any key." on the mkdocs theme. Coming right up.

mreinhardt · 2016-11-23T22:00:34Z

@waylan Amended commit with requested fixes.

waylan

Looks good. The search/help modal weirdness is resolved sufficiently. I still wonder if all keyboard shortcuts should be disabled when any modal is open, but this is a clean alternative and probably easier to implement.

I really liked being able to completely navigate through the entire site only from the keyboard. Address the few minor issues I highlighted inline and this should be ready to go.

Thanks for doing the work on this.

waylan · 2016-11-24T17:09:38Z

mkdocs/themes/mkdocs/js/base.js

+                page = $('[role="navigation"] a:contains(Previous):first').prop('href');
+                break;
+            case 83:   // s
+                if (e.altKey) {


Curious why you saw the need to require the Alt key here? I'm fine with it, just wondering why we can't use an s alone.

Umm, good question! I don't remember. Just s seems fine, will change.

waylan · 2016-11-24T17:15:24Z

mkdocs/themes/mkdocs/keyboard-modal.html

+                    <td>Open this help</td>
+                  </tr>
+                  <tr>
+                    <td><kbd>←</kbd></td>


Perhaps we should use the HTML entity (←) rather than the Unicode character in the template. With the proper encoding the Unicode character should work, but the HTML entity is less likely to break across various platforms, browsers, servers, etc.

You got it.

waylan · 2016-11-24T17:16:07Z

mkdocs/themes/mkdocs/keyboard-modal.html

+                    <td>Previous page</td>
+                  </tr>
+                  <tr>
+                    <td><kbd>→</kbd></td>


And this should be the HTML entity →.

waylan · 2016-11-24T17:28:23Z

mkdocs/themes/mkdocs/keyboard-modal.html

+                    <td>Next page</td>
+                  </tr>
+                  <tr>
+                    <td><kbd>Alt</kbd>+<kbd>s</kbd></td>


I noticed that the plus sign looks out-of-line (vertically) with the Alt and s keys. Its a nitpick, but it would be nice to get it right.

Actually, as per this, you should have:

<td><kbd><kbd>Alt</kbd>+<kbd>s</kbd></kbd></td>

That way, the plus sign is still in the outer kbd element, but separate from the actual keys in the inner kdb elements. Then just apply the key styling to the inner elements. That may resolve the issue itself. If not, then it at least provides an extra styling hook.

Removing Alt in shortcut so this will go away, but good to know.

waylan · 2016-11-24T17:34:12Z

Oh, one more thing, if you rebase against the upstream master branch, then the failing tests will go away as we've addressed that issue.

mreinhardt · 2016-11-26T00:03:46Z

Will do!

mreinhardt · 2016-11-26T02:22:17Z

@waylan All done! (I hope.)

waylan · 2016-11-26T18:23:49Z

I'm happy with this. It just needs to be added to the Rease Notes. However, we haven't added a section for the next release yet. I expect we'll probably do a bug-fix release or two before our next point release. Actually the next point release will probably be 1.0.0, and this has been assigned to that milestone so we won't forget it.

mreinhardt · 2016-11-28T17:21:41Z

Excellent, cheers!

waylan · 2017-10-03T14:18:44Z

Hmm, looks like I forgot about this. @mreinhardt if you update this to the current state in master, I'll merge this in.

mreinhardt · 2017-10-03T16:58:33Z

this is no longer the email address for @mreinhardt he no longer works here

…

On Tue, Oct 3, 2017 at 7:18 AM, Waylan Limberg ***@***.***> wrote: Hmm, looks like I forgot about this. @mreinhardt <https://github.com/mreinhardt> if you update this to the current state in master, I'll merge this in. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1095 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAjjPSCZGeCMu_7Ss6C1pjhzDbyS4YSRks5sokJJgaJpZM4K0vOJ> .

-- Mike Jeon GoodRx, Inc. VP Finance (310) 593-9977 (w)

waylan added this to the 1.0.0 milestone Nov 17, 2016

waylan added the Enhancement label Nov 17, 2016

mreinhardt force-pushed the keyboard-nav branch from 59182e5 to 88de372 Compare November 18, 2016 14:55

mreinhardt force-pushed the keyboard-nav branch 2 times, most recently from abadc03 to 8f78c0a Compare November 18, 2016 14:59

mreinhardt force-pushed the keyboard-nav branch from 8f78c0a to 8682d8a Compare November 18, 2016 17:41

mreinhardt force-pushed the keyboard-nav branch from 8682d8a to 12a65f1 Compare November 23, 2016 22:00

waylan requested changes Nov 24, 2016

View reviewed changes

Add keyboard navigation

42e22aa

mreinhardt force-pushed the keyboard-nav branch from 12a65f1 to 42e22aa Compare November 26, 2016 02:21

waylan approved these changes Nov 26, 2016

View reviewed changes

waylan self-assigned this Dec 2, 2016

waylan added the Update needed label Oct 3, 2017

Merge branch 'master' into keyboard-nav

e586e8d

waylan merged commit 9f5365a into mkdocs:master Oct 3, 2017

pols12 mentioned this pull request Jun 5, 2018

Change keyboard navigation keys #1502

Closed

Add keyboard navigation #1095

Add keyboard navigation #1095

Conversation

mreinhardt commented Nov 17, 2016

waylan commented Nov 17, 2016 • edited Loading

mreinhardt commented Nov 17, 2016

waylan commented Nov 17, 2016

waylan commented Nov 17, 2016 • edited Loading

mreinhardt commented Nov 17, 2016

mreinhardt commented Nov 17, 2016 • edited Loading

waylan commented Nov 17, 2016

mreinhardt commented Nov 17, 2016

waylan commented Nov 17, 2016

mreinhardt commented Nov 17, 2016

d0ugal commented Nov 17, 2016

mreinhardt commented Nov 18, 2016

waylan commented Nov 18, 2016

mreinhardt commented Nov 18, 2016

mreinhardt commented Nov 21, 2016

waylan commented Nov 22, 2016

waylan commented Nov 23, 2016

waylan commented Nov 23, 2016 • edited Loading

mreinhardt commented Nov 23, 2016

mreinhardt commented Nov 23, 2016

waylan left a comment

Choose a reason for hiding this comment

waylan Nov 24, 2016

Choose a reason for hiding this comment

mreinhardt Nov 26, 2016

Choose a reason for hiding this comment

waylan Nov 24, 2016

Choose a reason for hiding this comment

mreinhardt Nov 26, 2016

Choose a reason for hiding this comment

waylan Nov 24, 2016 • edited Loading

Choose a reason for hiding this comment

mreinhardt Nov 26, 2016

Choose a reason for hiding this comment

waylan Nov 24, 2016 • edited Loading

Choose a reason for hiding this comment

mreinhardt Nov 26, 2016

Choose a reason for hiding this comment

waylan commented Nov 24, 2016

mreinhardt commented Nov 26, 2016

mreinhardt commented Nov 26, 2016

waylan commented Nov 26, 2016

mreinhardt commented Nov 28, 2016

waylan commented Oct 3, 2017

mreinhardt commented Oct 3, 2017 via email

waylan commented Nov 17, 2016 •

edited

Loading

waylan commented Nov 17, 2016 •

edited

Loading

mreinhardt commented Nov 17, 2016 •

edited

Loading

waylan commented Nov 23, 2016 •

edited

Loading

waylan Nov 24, 2016 •

edited

Loading

waylan Nov 24, 2016 •

edited

Loading