Support theme context for images in light vs dark mode

I have transparent svgs, instead of changing my svgs to have white backgrounds, should this be possible to handle in the markdown itself?

GitHub Flavored Markdown Spec doesn’t seem to have a way to handle this at the moment unless you want to change all your images to html.

Might be cool to have a “default image background” setting on your repo for older repos that don’t look good in dark mode where people don’t have time to modify their images to look good in dark mode.

I think this might be my solution for now:

find . -name '*.svg' -exec sed -i'' '0,/style="width/s//style="background-color:white;width/' {} \;

Hi @BlackthornYugen - thanks for reaching out! I’m going to merge this with a similar topic related to supporting theme context for images in light vs dark mode. This has been a huge point of feedback since our beta launch and is something our team will start investigating potential solutions for this week. Its super helpful to have additional use cases - like svgs in old repos - for our internal exploration! :pray:

Thanks for the update. GitHub is (yet again) one of the few companies actually listening and responding, so please excuse my slight grumpiness in the beginning, as this is unfortunately not something I am used to when it comes to other services and their issues.

Looking forward to whatever your team comes up with to fix this.

Oh, and one more suggestion for just images. A lot of suggestions (as well as the ones I made) assume you changing the actual md file. GitHub could implement something that doesn’t need you to change your markdown, but to add alternative image files. For example, a current markdown file could look like this:


Let’s suppose the directory “media” currently only has the file “logo.png” in it, which is black and looks bad in dark mode. Without changing the original markdown file, you could then add the file “logo-light.png” to that same directory. GitHub could then, with CSS or even just with altering the md-to-html conversion, display that alternate light logo image in dark mode if and only if it’s in that same directory. If there’s no alternate image, then don’t change anything.

Some research:


@gaknoll Any updates


@gaknoll is there any timeline for this feature?

1 Like

I should definitely stop coming here everytime I look at my ugly readme logo with a white background, it’s always a disappointment. :smiley:


How did the workshop go?

What is the status on this? Breaking 90% of READMEs seems pretty careless and not having this as a top priority already all the way back in December is astonishing.


Yep, I just read all the comments but still no fix. We definitely need some solution for this issue.


breaking 90% of readmes

wut? @tskj - i dont think that number is even remotely accurate - how many readmes are on

I looked at 10 readmes today on GH and didnt have a problem with any of them. Maybe I’m special (I am a special kind of idiot), but I think in this case its because I didn’t opt into a beta feature.

If it is not working for you and breaking so much productivity, rather than continue feeling that pain I’d suggest that you opt out of the beta immediately and open a bug for the problem.


Normally I would agree but as a maintainer you want your readme to be readable for everyone (or at least the most amount of people possible). In general, your project should be acessible and endure a wide range of system configurations, environments and opinions.

For example, I personally don’t understand why people use yarn or a four years old node.js version or Angular, and we could argue about it for hours, but instead I’ll just make sure these people can use my project as it is, no matter how dumb their configuration/opinion is in my mind. Ideally. These are popular and established, it would just be stupid to make my project somehow “incompatible” with them, if I want people to interact with it.

Sure, I can turn off dark mode but I’m not writing my readmes for myself, but for everyone else, of which apparently a lot enabled dark mode already.

1 Like

I would rather not get an email a day with people asking “what’s the update”. They’ve made it clear they’re working on it. I keep notifications on so that when there is a solution from Github to a feature that is in Beta, I’ll see it.

Please keep the conversation here at a minimum unless you’re actually contributing to the solution with suggestions. (nnmrts you had some great ones up above!)


Sorry for spamming this thread but I solved this by adding both dark and light icons to my page:

Until we get something more definitive this is the only workaround I could think of.

Works with the new “dimmed” too, sort of… noticed on mobile the “default light” is actually very light grey so it’s far from perfect… but perfect from far!


I found this about generally supporting dark mode and images, so I tried using the raw html, but apparently <picture> is still sanitized

  <!-- Use this image if the user's OS setting is light or unset -->
  <source srcset="photo-light.png" media="(prefers-color-scheme: light) or (prefers-color-scheme: no-preference)">
  <!-- Use this image if the user's OS setting is dark -->
  <source srcset="photo-dark.png" media="(prefers-color-scheme: dark)">

I think this html might be the right way to handle this, unless new markdown syntax is going to be introduced.

I don’t easily have the option to change my svg’s right now, they’re being generated by plantuml. but I guess I can simply give them a background.

also noting that it’s now april :cry:

1 Like

Welp, Dark Mode is out of beta now, everyone can now set their GitHub to Dark Mode. Which means even more people will see messed up readmes and even more developers will be inclined and somewhat even forced to change their files and make their readmes mode-independent. Which is actually a lot of work, for example, adding a white background to a transparent png might sound like a quick task but have fun doing that for multiple pngs in tens or hundreds of repositories, each of which you have to push and review. And the end result will be absolutely ugly too on either dark or light mode. And all that will probably be completely worthless and just lost time once theme context will eventually be implemented.

Will there be any communication or vague information about how it will be implemented until that day is here? Or will the by far most viewed, not implemented feature request in this category be ignored for another three straight months?


Not related to this issue, you might want to make your own for that.

1 Like

@gaknoll I love the dark theme! But READMEs where supposed to be low-mantainance, easy to set up home sites for projects. I don’t think context info to know which theme is being used is going to really help repo mantainers. I’m not saying you can’t add context info for maintainers of big projects that want a lot of control in their mds (and in that case i’d suggest a metavariable such as @theme that can be used to generate paths such as img/logo_@theme.png), but really, we need sensible defaults.

I suggest two possible ways to deal with this that don’t break existing repos until mantainers can transition to the new situation.

  1. Default to adding a white background to images for now, which is a relatively simple css fix. Some READMEs will look bad in terms of design, yes, but all the content will be readable.

2 ) Render READMEs and ipynb with a white theme. The rest of the site can be dark, which again may not be perfect in terms of appearance but still preserves readability.

Maybe thise could be a repository options you could turn off, such as “Always render markdown pages with a white background, even if the user has a dark theme”. Therefore, if repository mantainers can’t provide an easy fix to their images, they can force a white background. The same idea of a repository option can be applied to adding white backgrounds to images.


+1 for this feature. I should add a background with an opacity in my logo to display in dark mode :frowning:


I think that this feature using something like @theme or {{ctx.theme}} or whatever will be amazing for the community!!

I tryied something more “hacking”, adding a CSS into my .svg using the root [data-color-mode] attribute that github inserts on <html>, like this:

      *[data-color-mode="dark"] path {
           fill: white;
    <path ... >

Unfortunately, this approach didn’t work :cry:

I tryied use the :root selector as well, but I think that the .svg don’t get the selectors from the parent of github html!