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

docs.rs/templates/style.scss

Line 6 in 731d031

// COLORS - Guess what?

.

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