That was my first attempt to solve the issue, but as you say, it can be awful on colorful images. The drop shadow seemed to me the most easy and general fix.
I have not found a way to do a solid outline with a simple CSS rule, that might be better, if anyone now how to do that.
Solid outline can be faked with 4 or 8 sharp shadows offset by 1 pixel.
There's also a trick:
filter: invert(1) hue-rotate(180deg);
that preserves colors while inverting brightness. Some logos will still look strange, but not as much.
filter: drop-shadow(1px 0 0px #fff)
drop-shadow(0 1px 0 #fff)
drop-shadow(-1px 0 0 #fff)
drop-shadow(0 -1px 0 #fff);
looks like this:
I applied different filters to 6 logos: std, async-std, bastion, rocket, unicode-segmentation and yew. The filters are:
filter: drop-shadow(0 0 5px #fff)
filter: drop-shadow(1px 0 0px #fff) drop-shadow(0 1px 0 #fff) drop-shadow(-1px 0 0 #fff) drop-shadow(0 -1px 0 #fff)
filter: invert(1) hue-rotate(180deg)
filter: brightness(2)
This is how they look like:
My conclusion is that there is no optimal filter for all logos.
I therefore suggest to make the filter configurable: The default filter for the Rust logo is Inverted, the default filter for all other logos is Unchanged.
P.S. this could be overridden with e.g.
#![doc(html_logo_url = "https://example.com/logo.jpg")]
#![doc(html_logo_dark_theme_filter = "outline")]
It seems like #3 looks the best across the board.
For me it's #4; Inverted, on my Mac laptop screen the #1, #2, and #3 versions of "async-std", the only logo with significant text, are essentially unreadable.
I found a few more crates with a custom logo: tracing, static_assertions, sauron, tide, rusoto_core, tonic, rio, amadeus, digest, curve25519_dalek, geo, rug.
I'd like to point out that very few crates use a custom logo, so we should prioritize the default one, which is the Rust logo.
I personally find (4) to be the best of those options. However, it would probably be a decent idea to allow authors to explicitly provide separate light and dark theme logos, just in case they don't like the default behavior. If that were allowed, I would strongly prefer (3).
As i mentioned in the issue, this isn't actually possible. It's only possible for the website favicon because we're changing based on the browser theme (which can be checked in CSS). There's nothing for user-defined themes.
I really think that just allowing content to provide two logos is fine. Yes, you can add your own themes as well. However, most themes fall in a "light" or "dark" bucket. Even CSS restricts itself to these two. We should make it possible for a theme to be defined as light or dark and give content the ability to set two logos if they desire. Given that the original issue was that the Rust logo was not looking good here I think we can at least start off with an internal only feature for this that fixes it for Rust and then discuss polishing it up so that it works for custom logos.
I think both approach are complementary. We should allow to provide an image for dark themes and apply a filter if it is not provided, since I agree with @GuillaumeGomez that most crate owner won't provide two logos.
Options 3 and 4 seem a correct fallback to me. I personally prefer option 3 since it does not alter the logo colors. async-std look better on option 4 but yew is completely broken.
Thanks for the comparison @Aloso!
I also think that option 3 is the best amongst the 5 suggested ones.
I toyed with it a little bit, the result is similar to option 4 : the colors can be broken on some images.
If possible I'd prefer to retain control over how the logo is rendered on docs.rs; the http-rs logo was designed to look good regardless of background color.
However it currently doesn't particularly look great with the faint white glow around it. Ideally there wouldn't be a border, so we can keep consistency between the rendering with the docs.rs favicon and GitHub as well.
docs.rs sidebar
GitHub
docs.rs favicon
It's possible to choose the optimal method by analyzing the image itself (checking contrast with pixels that are neighboring transparent pixels).
I still think we should not try to autodetect, and just let people specify a logo for light backgrounds and a logo for dark backgrounds. If their logo works in both cases, they can specify the same logo twice.
I think everybody agree that the best is to let the documentation provide two logo (and eventually the same twice).
The problem is what to do if the documentation provide only one. Do we force to provide two logo to display anything ? The one pixel outline seem the best fallback to me.
I strongly agree with you. Providing two images is just not manageable.
