Add mdbook docs page

[ericholscher]

This shows how to host docs with mdbook.

Requires #11848 to not need a reshim (example: https://github.com/readthedocs/test-builds/blob/mdbook/.readthedocs.yaml#L10)

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11849.org.readthedocs.build/en/11849/

• Developer's documentation (dev): https://dev--11849.org.readthedocs.build/en/11849/

[humitos]

Looks good!

There are some things we should add to this guide:

1. Integration with search to trigger ours when clicking on the search icon. Similar to what we wrote for MkDocs: https://docs.readthedocs.io/en/latest/intro/mkdocs.html#configure-read-the-docs-search
2. Add custom CSS for flyout size
3. Our search seems broken in the example. You cannot type the s letter for example.
4. It would be good to add a small paragraph at least in the test-builds project 😄 . It only says "Chapter 1"

[humitos]

You should add custom CSS files to make the flyout looks nice; it's pretty small now:

See an example for MkDocs: https://docs.readthedocs.io/en/latest/intro/mkdocs.html#adjust-the-flyout-menu-font-size

[humitos]

Have you tried using build.jobs.build.html instead? I think we should be recommending as much as possible that approach.

[ericholscher]

I haven't, but thought this was blocked on #11819

[ericholscher]

@humitos Should we be doing similar default configuration for the addons CSS selectors here, where we're able to detect the doctool and configure the Addons font size for example? It seems bad to punt this to the user if we know there's specific config we want for a tool, and we have the functionality to be able to detect the tool? 🤔

I feel like we're gonna get closer and closer to having magic on the front end if we keep adding in all these special cases tho, but I think it's unavoidable if we want to provide 💯 integrations for some of these tools.

[humitos]

Yes. I've been on the fence about adding those CSS rules automatically; but since they are --readthedocs-* specific CSS rules --so it's something we control and shouldn't have any impact in any other UI elements. Besides, I think we would want to add an option to opt-out from them "just in case" users are getting bad results (e.g. incorrect documentation tool detection, bad results, etc).

[ericholscher]

@humitos This worked nicely in my test: https://test-builds.readthedocs.io/en/mdbook/

But it seems like the s key is hosed when search is open, because they're hooking into that to trigger their own search. 🙃

[humitos]

Looks great!

I remember having a similar issue with Material for MkDocs. They ended up fixing the issue on their side by skipping handling the keydown if the focus was inside a text input.

The options I see here are:

• Disable their own search
• Disable their hotkeys

I'm not sure if that's possible, tho.

[ericholscher]

I'd like to get this merged so we can start ranking for it, and then futz with the final details of integration?

[humitos]

Looks good, we can merge this.

There are some points we want to do after:

• Continue the investigation for auto-CSS (Add styles based on the documentation tool addons#473)
• Disable their search / Fix the s key
• Migrate the YAML example to build.jobs.build.html

[ericholscher]

Looks like the code for this is here:

https://github.com/rust-lang/mdBook/blob/master/src/theme/searcher/searcher.js#L331-L335

Not really sure how to handle this -- I know we hit something similar with Mkdocs Material, but don't remember how we solved it.

[humitos]

I know we hit something similar with Mkdocs Material, but don't remember how we solved it.

They solved on their side. I commented this in the previous thread 😄 : #11849 (comment)

[ericholscher]

I opened rust-lang/mdBook#2507