mdBook
mdBook copied to clipboard
rust-lang
[Feature request] make keyboard nav optional
Hi!
I'm currently reading the Rust book, which is awesome in many respects, but I regularly trigger the next/previous page events by pressing the arrows (it's kind of reflex, I'm not even sure of why I use those keys, but I suppose I rely on them usually being noops). It would be nice if there was a way to disable them permanently (short of forking mdRust and serving a custom build of the book on localhost).
Since they are AFAICT undocumented and non-standard, those shortcuts also have discoverability issues for people who would benefit from them.
While it would clobber the UI, a checkbox would also raise the awareness of the feature.
Technically this wouldn't be very difficult to do. You'd just add a checkbox and whenever the page loads or the checkbox is toggled, the appropriate event handlers are updated. However, I'd be a little hesitant to add an extra thing to the UI for just deactivating the arrows. Just because it'll end up adding clutter to the UI and it's an extra thing which needs to be maintaned, my concern is the feature wouldn't be used enough to warrant the effort.
Another thought is to have a more general "config" overlay, similar to what the playground does. That way you've got a mechanism for UI tweaking, it'd be out of your way by default, and more maintainable in the long run.
i.e. Something like this:
It may be useful to ask people who work on The Book or Rust By Example and see if they've seen similar UI issues raised before. That would help us get a feel for how desired the ability to tweak the UI is.
cc: @carols10cents, @steveklabnik, @budziq, @projektir (feel free to cc in anyone else who may have an opinion)
I can see where you're coming from...
The thing I wonder is why you have it as it is in the first place, i.e. non-standard, hidden.
Who's the target audience for the feature?
I'd expect people with screen readers are used to tab + enter to activate the buttons.
The web sites/apps I use the most (GitHub, Reddit, HN, Gmail) all ignore the left/right arrows... is it common in reader apps?
Edit: OTOH, if you were to remove it now, the people who got used to the feature would also complain...
I remember the first time I was reading through The Book and was surprised that hitting the right arrow did exactly what I wanted, i.e. it went to the next chapter. It's an intuitive thing to do, especially when all browsers let you use the up and down arrows as an alternative to scrolling around a page.
The thing I wonder is why you have it as it is in the first place, i.e. non-standard, hidden.
I believe the best answer to this is probably "because that's what GitBook does" (example) and mdbook was originally designed to be compatible with GitBook.
I believe the best answer to this is probably "because that's what GitBook does" (example) and mdbook was originally designed to be compatible with GitBook.
The arrow keys don't seem to do anything at that example (any more?). This is interacting badly with a textarea I have. It would be nice to be able to disable this in book.toml at least.
It's an intuitive thing to do, especially when all browsers let you use the up and down arrows as an alternative to scrolling around a page.
No, it's a highly unintuitive thing to do:
- When a text field isn't focused, the default and thus expected behavior of left/right keys in a web browser and most other apps is to scroll from left to right (no-op if the page is already full-width).
- Following from 1, most sites/apps don't implement left/right as previous-page next-page.
- It's very easy to hit left/right by accident when you're scrolling with up/down (the keys are right next to each other).
- Pressing down followed by up cancel each other out (scroll down, then up). Pressing right followed by left do not, because you lose your scroll position on the previous page.
- Following from 4, it's an example of deleting user-specified information (the information about the scroll position) without asking the user's permission.
IMO the sensible default would be to disable this feature, and maybe provide it as an opt-in legacy option or (better) use a less common and easily mis-hit shortcut instead, such as Ctrl+left/right.
I absolutely despise the left/right arrow keys. I use up/down to scroll the page and often hit the right key by mistake. How can I disable this in book.toml for my project?
I still think forcing this on users by default is a terrible idea, for the reasons I outlined above and also the accessibility issues mentioned in https://github.com/rust-lang/mdBook/issues/1789, but for individual users who want to disable this behavior for mdBook and GitBook, I made a tampermonkey script that'll do the trick: https://gist.github.com/lionel-rowe/25b9ccf76379e3e12988bff837f6f492
It also reduces the hitbox size of the clickable nav buttons on either side of the page, which are easy to click by accident (the problem's even worse for GitBook, as its default styles don't change their background on hover, so you end up clicking what looks like a blank space on the page and then getting navigated away).
Who's the target audience for the feature?
I use it extensively in https://google.github.io/comprehensive-rust/ — which is a book disguised as a presentation :slightly_smiling_face: It works perfectly in that context (which I agree isn't the main use-case for mdbook). Perhaps this is where the inspiration comes from? Presentation software often uses the arrow keys to let you page through a presentation.
I remember the first time I was reading through The Book and was surprised that hitting the right arrow did exactly what I wanted, i.e. it went to the next chapter. It's an intuitive thing to do, especially when all browsers let you use the up and down arrows as an alternative to scrolling around a page.
Yep, I use it all the time too in various books. I find it really nice for keyboard-only navigation — browsers generally don't have a way for you to "go to next page", but for a book, that is badly needed.
How can I disable this in
book.tomlfor my project?
You have to copy the book.js file to your theme/ directory and modify the shortcuts there.
I have custom editable elements on my page and this behaviour makes my editbox element unusable.
Is mdBook meant to be locked-in to just the Rust Playground and not to be used with anything else?
I have custom editable elements on my page and this behaviour makes my editbox element unusable.
Can you explain more what problems you see? (Possibly in a new issue). In my experience, there is no conflict with editable code blocks: when the focus is in the code block, the arrow keys don't navigate between pages. I use it all the time, e.g., here: https://google.github.io/comprehensive-rust/cargo/code-samples.html.
there is no conflict with editable code blocks
...because it's part of mdbook itself.
Like I said, the issue is with custom elements not part of your framework, mdbook simply does not recognize that I'm in the edit mode of my own implemented editbox
I don't think this warrants a separate issue since this is exactly identical to what is being described within this issue, just in a different use case where someone might add a custom form element to their page and mdbook does not respect anything other than its own Playground.
I am a screen reader user and this feature makes it really difficult for me to focus on specific words and especially lines of code. Does anyone know when this will be fixed?
