pypi/warehouse

Github Dark Mode Image Support

mwarkentin opened this issue · 12 comments

mwarkentin commented

What's the problem this feature will solve?
Github supports rendering a specific image for light vs. dark mode by actually specifying two images. Here's an example PR: getsentry/sentry#33799

However when the .md file is rendered elsewhere (like pypi) it would show up as 2 images.

Describe the solution you'd like
It would be great if pypi could show light mode images only, and hide dark mode images (since pypi doesn't have a dark mode). If pypi ever adds a dark mode feature, it could use the correct image at that time.

Additional context

di commented

I've transferred this issue to https://github.com/pypa/readme_renderer/, but this is likely blocked on a change to our underlying GitHub-flavored Markdown formatter, https://github.com/theacodes/cmarkgfm

  • 👍1
mwarkentin commented

@di thanks - should I open an issue over there?

di commented

Yep

  • 👍1
mwarkentin commented

@di looks like this is just done in CSS on Github:

GH implements this very naïvely/smartly with CSS. Basically:

@media (prefers-color-scheme: light) {
  /* ^-- browser/os setting */
  :root[data-color-mode=auto] .markdown [href$="#\gh-dark-mode-only"] {
    /* ^-- gh theme */
    display: none
  }
}
di commented

Sorry, I should have looked at the PR you linked. Is the user required to write HTML to do this? Is there not a way to add dark mode images in markdown?

If it's just HTML, I think we can just add that snippet to PyPI's CSS styles.

mwarkentin commented

@di it can be done in markdown as well (but I think this just renders out to the same HTML as we wrote?):

![GitHub Dark](https://github.com/github-dark.png#gh-light-mode-only)
![GitHub Light](https://github.com/github-light.png#gh-dark-mode-only)
di commented

Ah, I see, thanks! Transferring this back to https://github.com/pypa/warehouse. Please feel free to create a PR if you'd like.

mrgrain commented

GitHub now also supports the <picture>.
https://github.blog/changelog/2022-08-15-specify-theme-context-for-images-in-markdown-ga/

Ideally <picture> would be supported, but a simple implementation could remove everything bar the <img> tag.

  • 👍4
Hartorn commented

Hey, just coming here to get some news on this : do you plan to add this css code snippet to pipy css ?
Having the same issue with https://pypi.org/project/giskard/2.7.1/

cofiem commented

Hello,

I am thinking about adding a dark mode for PyPI using Sass variables, CSS Variables and @media (prefers-color-scheme: dark).

I have a couple of questions before I start:

  • Would a PR for a dark mode be accepted?
  • The typical approach is to default to light (the current PyPI theme), and change to dark based on the browser / OS settings. Is that reasonable?
  • Which browsers does PyPI aim to support? CSS variables are supported in the modern browsers since about 2017, with some issues in Edge.
  • Is there a need for having a dark / light mode toggle on the page? Or is the media query sufficient? I would use the media query and not offer an in-page toggle. The in-page toggle can be added later via javascript if required.
  • The implementation I am thinking of would be similar to these descriptions - one, two. Would that be acceptable?

Related issues:

miketheman commented

@Hartorn Do we plan on adding it? Sure, if someone contributes the right working solution, but no pull requests have been submitted yet.

Hey @cofiem ! Thanks for putting together specific questions, will try to answer them here:

  • Would a PR for a dark mode be accepted?

If it's a good one and works, probably!

  • The typical approach is to default to light (the current PyPI theme), and change to dark based on the browser / OS settings. Is that reasonable?

The current theme could be considered light, and the default. Yes, it's reasonable to switch on and off based on browser theme.

  • Which browsers does PyPI aim to support? CSS variables are supported in the modern browsers since about 2017, with some issues in Edge.

See https://warehouse.pypa.io/development/frontend.html#browser-support

  • Is there a need for having a dark / light mode toggle on the page? Or is the media query sufficient? I would use the media query and not offer an in-page toggle. The in-page toggle can be added later via javascript if required.

Having toggles is something useful for users, and I'd like to give them the flexibility to do so, especially since as this is developed there might be pages that definitely look "wrong" in dark mode until it's fully ironed out. Persisting user's choice there would be preferred.
See examples in Furo (warehouse dev docs), mkdocs-material, which we use for PyPI Blog and PyPI Docs - they all detect the media query, but preserve user control, and persist the setting in browser localstorage

  • The implementation I am thinking of would be similar to these descriptions - one, two. Would that be acceptable?

Probably? Without delving too deeply into either post I can't sty for certain. Our SCSS stack vendors bourbon 4.2.5 (definitely needs an update/upgrade), so if they have any built-ins that can help, that might make things a little easier.

Also keep in mind that picture support was recently added and released in readme-renderer 43, so it'll take a bit until that makes its way into warehouse via dependeabot which is now live on warehouse.