rust-lang
Migrate to rinja
Main argument for switching to rinja: compilation fails if your template is invalid. It also generates very performant code (as can be seen here).
Some extra advantages: it makes the code simpler to follow. Storing everything into a JSON map made it pretty tricky to understand what was going on and needed to have a lot more checks in the code.
With this JSON map gone, I also simplified code to handle chapter kinds: it's now a Chapter enum, making it easier to understand.
Last point: rustdoc, docs.rs and clippy lints page already switched to rinja so I think it tells a lot about how reliable rinja is. :)
Considering how big the PR is, please don't hesitate to ask me if anything is unclear.
In the current version of mdBook, mdbook init --theme drops copies of the hbs files that book authors can then modify, allowing them to change the HTML without recompiling.
This PR seems to remove that functionality. I don't think that's a good idea without first taking stock of customization that popular books use, helping them migrate over to some better way(s) to accomplish the same things, and only then deprecating and removing support for custom hbs.
In any case, you really need to mention stuff like that in the PR description.
I didn't realize it was a feature. I saw a test checking that but didn't check further, should have. Gonna investigate.
- bevy cheat book is using JS to modify the pages.
- Rust official books don't seem to update this file.
- rinja book doesn't modify it.
- askama book doesn't modify it.
- WIP
rust-by-example has a custom language picker, and zjp-cn has a custom TOC.
https://github.com/rust-lang/mdBook/issues/2490 adds their own logo.
The custom TOC is actually to add something that was missing at the time: TOC for headings in the current page. For rust-by-example it could be switched to JS.
So in here, I think we'll need to discuss more th @ehuss to see if adding options --html-before-content and --html-after-content to allow users to add their own HTML without modifying templates is acceptable, and if adding a --html-header-content to add their own content in <head> is ok. It could be a major release etc.
On one hand, it would make mdBook closer to rustdoc in this regard.
But in any case, I think the code simplification and having template errors at compile-time is a big plus.
Waiting to hear from @ehuss then. :)
:umbrella: The latest upstream changes (possibly #2681) made this pull request unmergeable. Please resolve the merge conflicts.
