Automatically use a dark theme according to 'prefers-color-scheme' #1037
Conversation
|
Thanks! Can you also update the documentation for the new option at https://github.com/rust-lang-nursery/mdBook/blob/master/book-example/src/format/config.md#html-renderer-options? I'm also thinking, if a book defines its own themes, this will break them if they don't have a theme named "navy". Perhaps it should somehow detect if the theme doesn't exist? |
|
@ehuss I've added the new option to the documentation. Isn't the current behavior for a missing 'navy' theme the same as for missing the default 'light' theme (i.e. removing the Also, it seems the CI build is failing from a file not touched by this PR. Should I fix that to make the build pass or leave it as-is? |
Presumably if someone customizes the themes, they either have a "light" theme, or change the default in the config.
That might be a little clearer, but I would prefer not to make intrusive changes like that. Can the javascript just query if the default dark class is defined, and if not just fall back to the default theme (as-if the
Looks like the new rust release today had a minor rustfmt change. I went ahead and fixed it, so no need to do anything about it. |
|
@ehuss What if we have a note in the docs to set preferred-dark-theme to the same value as default-theme to disable it?
Could that same logic also apply to preferred-dark-theme? |
That would be a good thing to add to the docs. But I'd still prefer not to make a breaking change for anyone that has custom themes. It does seem annoyingly difficult to query from javascript. How about a compromise, for now set the default to the same as |
|
@ehuss Okay, sounds good. I've changed it as you suggested. |
|
Thanks! I'll open an issue to track changing the default. |
Upgrade to mdBook v0.3.7 This bumps the requirement from Rust v1.34.0 to v1.35.0 for building docs. AFAICT CI is using nightlies so that should be fine, but I thought I'd mention it in case someone thinks this impacts contributors in any way. Other than that, there are a few changes that might impact some users in a visible way, like automatic dark theme support for those who picked that perference in their browser, possible color changes to the scrollbar and to the font size, change in the spacing in the sidebar entries, and many more changes and fixes that won't be too immediately impactful but very good all around. I checked changes from transitive dependency bumps as well, AFAICT there is nothing that *should* impact the final rendering. **tl;dr:** Nothing will explode. Probably. For completeness, my raw notes of outtakes as I was reviewing the change logs: ``` [cosmetic] v0.3.2 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-032 Added automatic dark-theme detection based on the CSS prefers-color-scheme feature. This may be enabled by setting output.html.preferred-dark-theme to your preferred dark theme. #1037 rust-lang/mdBook#1037 v0.3.3 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-033 Improvements to the automatic dark theme selection. #1069 rust-lang/mdBook#1069 v0.3.7 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-037 Fixed theme selector focus. #1170 rust-lang/mdBook#1170 * https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme * users who picked the dark color scheme in their browser will see the cargo doc in dark. [cosmetic] v0.3.2 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-032 Use standard scrollbar-color CSS along with webkit extension #816 rust-lang/mdBook#816 * https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-color * scroll bar color might change i guess. [helpful] v0.3.2 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-032 Updated highlight.js for syntax highlighting updates (primarily to add async/await to Rust highlighting). #1041 rust-lang/mdBook#1041 * not sure cargo doc has many code examples with async/await, but there we go. [warning] v0.3.2 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-032 Raised minimum supported rust version to 1.35. #1003 rust-lang/mdBook#1003 * from 1.34.0. [cosmetic] v0.3.4 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-034 Switch to relative rem font sizes from px. #894 rust-lang/mdBook#894 * will impact some displays, but px is already an abstract thing so maybe not that big of an impact. [warning] v0.3.5 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-035 Updated pulldown-cmark to 0.6.1, fixing several issues. #1021 rust-lang/mdBook#1021 * from 0.5, breaking changes. * parsing only -- the team had to do multiple changes but nothing seems like it would impact final rendering [cosmetic] v0.3.6 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-036 Adjusted spacing of sidebar entries. #1137 rust-lang/mdBook#1137 [warning] v0.3.6 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-036 Handlebars updated to 3.0. #1130 rust-lang/mdBook#1130 * from 2.0 * https://github.com/sunng87/handlebars-rust/blob/master/CHANGELOG.md * strictly maintenance and perf AFAICS, no changes to final rendering. [cosmetic] v0.3.6 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-036 Adjusted the menu bar animation to not immediately obscure the top content. #989 rust-lang/mdBook#989 * personal fave. [cosmetic] v0.3.7 https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-037 Code spans in headers are no longer highlighted as code. #1162 * users will see some headers change, probably. [fixes] + ~13 fixes impacting rendering in less immediately visible ways. rest should have no impact on end-user experience. ```
Automatically use a dark theme according to 'prefers-color-scheme'
This PR makes mdBook automatically use a dark theme if prefers-color-scheme is set to 'dark'.