Please provide a dark theme for non-rustdoc pages on docs.rs

[joshtriplett]

The rustdoc pages on docs.rs have all the theme options rustdoc normally provides; however, the search pages and the front page always use a light theme, which can be jarring. I'd love to see an adaptation of ayu.css for the non-rustdoc portions of docs.rs.

[Nemo157]

There is a userstyle for this https://github.com/Cldfire/ayu-rs, and @Cldfire has expressed interest in getting it integrated into docs.rs proper.

[Cldfire]

I would be more than happy to work on this if we can come up with a plan that is satisfactory for the docs.rs maintainers.

I know @pietroalbini expressed concerns with the idea of styling the front page and such.

[jyn514]

More discussion on this around https://discordapp.com/channels/442252698964721669/541978667522195476/731948537591365642. The main thing that was hard was syncing the theme preference to the rustdoc selection, because we don't control rustdoc CSS or the way it stores preferences. If we started with a less ambitious goal of having a dark theme at all, I think this would be more doable.

@Cldfire are you interested in making a PR for adding a dark theme? The relevant code is https://github.com/rust-lang/docs.rs/blob/731d03183d1c65636cc98dc8be15768fe4725969/templates/style.scss#L6.

I guess another issue is how to switch between themes; right now docs.rs doesn't have a settings page at all. So maybe we should sync with rustdoc after all? I'm not sure how hard that would be.

[joshtriplett]

@jyn514

The main thing that was hard was syncing the theme preference to the rustdoc selection, because we don't control rustdoc CSS or the way it stores preferences.

Would it be simpler, rather than tying it to the rustdoc theme selection, to just use the user's browser setting for prefers-color-scheme? That would solve the problem for many people.

[jyn514]

Ooh, prefers-color-scheme is a great idea. Yes, that wouldn't be too hard to implement I think.

[Nemo157]

I think having an explicit toggle still is very important for browsers that don't support setting the colorscheme (preferably with a default "use prefers-color-scheme" option).

[Cldfire]

Would it be simpler, rather than tying it to the rustdoc theme selection, to just use the user's browser setting for prefers-color-scheme? That would solve the problem for many people.

My main fear with going this route is that it creates a poor UX for users of docs.rs. Instead of simply changing the rustdoc theme and seeing the appropriate change occur to the docs.rs bar at the top of the screen, you'd also have to go toggle the docs.rs theme. This seems like a unnecessary extra step that will quickly become annoying.

Also... what do we use for the "dark" theme styling? The ayu theme? Then it looks out of place with rustdoc's dark theme. The dark theme? Then it looks out of place with rustdoc's ayu theme. Not ideal.

The main thing that was hard was syncing the theme preference to the rustdoc selection, because we don't control rustdoc CSS or the way it stores preferences.

Agreed, this is a problem, especially when the "rustdoc-theme" value has not been set in local storage. The current logic in rustdoc is:

switchTheme(getCurrentValue("rustdoc-theme") || getSystemValue() || "light", false);

and we could of course replicate that in docs.rs, but there's no guarantee that it stays in sync with rustdoc.

Could we perhaps extract theme preference logic into a small, common JS lib that could be shared between docs.rs, rustdoc, and any other Rust-related sites that wished to sync with rustdoc theme selections? Then we could:

• Make sure we properly support prefers-color-scheme in both rustdoc and docs.rs
• Correctly sync theme selection between rustdoc and docs.rs

There remains the problem of rustdoc versioning; we'd need to make sure the extracted library was always backwards-compatible with previous versions of itself in order to properly support older docs on docs.rs.

This route is definitely more work, but it would result in a much nicer UX for docs.rs. Let's at least rule something like this out before we continue on with another idea!

[jyn514]

Could we perhaps extract theme preference logic into a small, common JS lib that could be shared between docs.rs, rustdoc, and any other Rust-related sites that wished to sync with rustdoc theme selections?

I like this idea. Cargo does something similar with https://docs.rs/cargo-platform/0.1.1/cargo_platform/.

[jyn514]

@seri on discord suggested using https://github.com/darkreader/darkreader#using-for-a-website once we implement the dark theme. Not sure if @Cldfire had a different design in mind though.

[Cldfire]

@seri on discord suggested using https://github.com/darkreader/darkreader#using-for-a-website once we implement the dark theme. Not sure if @Cldfire had a different design in mind though.

Hmm, that looks like a lot of JS to include just to provide a dark theme.

I'd much prefer to simply use CSS and keep added JS minimal to accomplish this goal 🙂.

[Kixiron]

Agreed, I love darkreader and use it as a daily driver, but in the wrong conditions it's absurdly heavy and large doc pages are a place it can struggle

[jyn514]

Agreed, this is a problem, especially when the "rustdoc-theme" value has not been set in local storage. The current logic in rustdoc is:

switchTheme(getCurrentValue("rustdoc-theme") || getSystemValue() || "light", false);

and we could of course replicate that in docs.rs, but there's no guarantee that it stays in sync with rustdoc.

Maybe we could implement that just for now and fix it the 'right way' later? It's only one line of code and it's a lot less hassle to deal with.

[Cldfire]

Maybe we could implement that just for now and fix it the 'right way' later? It's only one line of code and it's a lot less hassle to deal with.

I'm certainly fine with hardcoding things if other people would be ok with that as well. I'm just waiting for a consensus to be reached here before I go to the effort of implementing something 😄

[Nemo157]

So, I was thinking about how to get access to rustdoc's theme settings reliably, one approach that might work is to use a small worker to watch the storage events, allowing us to easily detect when rustdoc-theme changes and apply that theme to ourselves. That way we don't have to do any theme management ourselves, and can just rely on rustdoc's settings page and prefers-colorscheme detection (though it does mean we won't detect a change in prefers-colorscheme on the main docs.rs pages :thinking:).

[jyn514]

though it does mean we won't detect a change in prefers-colorscheme on the main docs.rs pages 🤔

We'll still pick it up the next time you visit a rustdoc page, right? That seems like enough of an edge case I don't mind if it's not handled.

[Nemo157]

I have a working implementation of watching the rustdoc theme (needs to use an iframe rather than a worker because for some reason neither dedicated or shared workers get the storage event when localstorage changes). That should work very well with rust-lang/rust#77809 doing the prefers-color-scheme detection for us. I will take a look at what's needed to actually get theming implemented.

[Cldfire]

That's awesome! I'm happy to help with the CSS once the theme infrastructure is in place 👍

[jyn514]

Added in https://github.com/rust-lang/docs.rs/pull/1116.