Published at
Updated at
Reading time

I was browsing the GitHub markdown docs to check something and spotted a new GitHub feature. ๐Ÿ™ˆ GitHub markdown finally supports light and dark mode images! It always bugs me when GitHub Readmes look super polished but include a terrible-looking "hero image" in the dark GitHub UI (or the other way around).

FYI โ€” GitHub deprecated URI fragments and favors the picture element now. Learn more below.

Use a URI fragment in the image URL to hide or show it depending on user preferences!

![Fancy logo](./dark.png#gh-dark-mode-only)
![Fancy logo](./light.png#gh-light-mode-only)

Here is it in action. ๐Ÿ‘‡

Light/dark mode images in GitHub markdown

I couldn't find official release notes about it, but the feature seems to be only a few days old. The new CEO shared it on Twitter, too.

The problem with non-standard solutions

While this approach seems smart, it comes with drawbacks. Appending #gh-dark-mode-only to an image URL works perfectly fine on That's not the only location many Readmes are rendered on, though. npm renders repo Readmes. Blogs render repo Readmes. GitHub Markdown can go anywhere!

Any site but GitHub will render two images with this new approach.

Thinking of npm, I'm sure they will adopt this syntax quickly (it's all Microsoft, right?), but it's probably too early to adopt this feature right now. And if you do, you better be sure that the Readme isn't rendered anywhere else because I don't see Markdown renderers implementing this soon...

GitHub rolls out the picture element

GitHub limits the number of allowed HTML in their Markdown to not open a massive can of worms. Imagine folks putting script tags in their Readmes โ€“ "oh hi, wonderful XSS attack". ๐Ÿ‘‹

But it's now great to see that GitHub is considering allowing the picture element for dark mode images GitHub supports the picture element. Yay!

  <source media="(prefers-color-scheme: dark)" srcset="./dark.png">
  <img alt="Text changing depending on mode. Light: 'So light!' Dark: 'So dark!'" src="./light.png">

I tested the addition in the example repo, and it works even with relative paths!

Read more about the feature in the GitHub markdown docs.

Was this post helpful?
Yes? Cool! You might want to check out Web Weekly for more WebDev shenanigans. The last edition went out 8 days ago.
Stefan standing in the park in front of a green background

About Stefan Judis

Frontend nerd with over ten years of experience, freelance dev, "Today I Learned" blogger, conference speaker, and Open Source maintainer.

Related Topics

Related Articles