The reason the ACE editor was failing to load the rust syntax
highlighting is because the syntax highlighting was being created
*after* the editor was created. If the editor is created first, then ACE
tries to load `ace/mode/rust`. Since it isn't already defined, it tried
to compute the URL and load it manually. However, since the URLs now
have a hash in it (via https://github.com/rust-lang/mdBook/pull/1368),
it was unable to load.
The solution here is to make sure `ace/mode/rust` is defined before
creating the editors. Then ACE knows that it can just load the module
directly instead of trying to fetch it from the server.
Fixes https://github.com/rust-lang/mdBook/issues/2700
This makes a few changes to the help popup:
- Move css to chrome.css, since this is a UI element.
- Move HTML code to index.hbs instead of generated in JavaScript.
In general I prefer to keep HTML out of JavaScript when possible,
and I didn't see a particular reason to avoid it.
- Added a click handler to dismiss the popup.
- Make sure handlers get removed when dismissed.
- Use `mdbook-` prefixes for IDs to avoid collisions with headers.
- Don't show search if it isn't enabled.
- Add the new `/` shortcut.
- Use flex layout for better positioning.
- Dim out the surrounding text using an overlay.
- Various other styling tweaks.
- Add a GUI test.
When describing, in the guide, the keyboard shortcuts that we accept,
let's use the `<kbd>` element. This causes the key to render in a box
that people will recognize as conventional.
The way that this is displayed helps to make it clear that, though we
present the key in uppercase, we actually mean for the lowercase
letter to be entered. Therefore, we present the key in uppercase
since 1) that's how it appears on most keyboards and 2) for some
characters such as `l`, presenting the character in lowercase might be
ambiguous.
We'll spell out "Escape" rather than saying "Esc" (even though many
keyboards spell it that way) since the `KeyboardEvent.keycode`[^1] is
called "Escape", and that's how it would appear in an
`aria-keyshortcuts` attribute[^2].
[^1]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode
[^2]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts
It's common for search boxes like ours to automatically navigate to
the first search result when the `enter` / `select` key is pressed, as
that can allow for rapid navigation. E.g., the MDN documentation does
this.
Let's similarly navigate to the first result when, in the search box,
the user presses the `enter` key and there is a first result to which
to navigate.
If, when searching, one pressed the down arrow key when there were no
results, this caused an uncaught exception and defocused the search
box.
Let's prevent this and keep the search box focused when pressing down
in this state by checking first whether there is a result for us to
focus instead.
We allow for using `s` to open the search box, but it's more common to
use `/` (forward slash) for this. E.g., MDN's documentation uses `/`
for search. Rustdoc and GitHub accept either.
Let's allow either key to be used, and let's switch to "advertising"
`/` rather than `s` in the hover text for the search button.
In making that switch, let's also simplify that hover text a bit.
Previously it had said "Search. (Shortkey: s)". This was the only top
button on which we had included a period in the hover text. Let's
remove that, and let's remove the "shortkey" bit of jargon. It's
enough to just put `/` in a parenthetical, i.e. "Search (`/`)".
People will gleam from that what we mean.
We've also updated the guide accordingly.
This skips serializing of the multilingual field since it is unused, and
we plan to remove it in the future. This helps avoid it showing up in
`mdbook init`.
Although there isn't a direct equivalent in the new testsuite, I felt
like these weren't adding any specific coverage that the existing tests
don't already exercise. If it does turn up that there is specific
coverage missing, then I would prefer to have tests which exercise the
specific thing of interest rather than have these kinds of non-specific
tests.
