Adapting README Images to GitHub’s Theme

GitHub lets users switch between light and dark mode, but a single static image can’t always adapt. A bright screenshot or diagram that looks fine in light mode can feel harsh or cluttered against a dark background. You can solve this by using the <picture> element directly in Markdown, letting the browser pick the right file based on the viewer’s color scheme.

This works in repository READMEs, GitHub-hosted documentation, and any other Markdown file rendered on GitHub.com. The syntax is simple enough to drop into any project, and it can make your visuals feel native to the theme instead of pasted on top of it.

The Snippet

Copy the following block into your Markdown file to define separate images for each theme:

<picture>
  <source media="(prefers-color-scheme: dark)">
  <source media="(prefers-color-scheme: light)">
  <img alt="Fallback image description" src="default-image.png">
</picture>

How It Works

The setup relies on three standard HTML behaviors:

  • <picture> is a container that lets the browser choose among multiple <source> entries.
  • Each <source> uses a media attribute to match the user’s preference. When media="(prefers-color-scheme: dark)" matches, the browser loads the image from that source’s srcset. The same applies to (prefers-color-scheme: light).
  • If neither media query matches, or if the browser lacks <picture> support, the fallback <img> tag is displayed.

GitHub respects the user’s theme setting, and the browser applies the corresponding prefers-color-scheme value, so the image swap happens dynamically without requiring any user action. While it’s a small addition, it makes the project look significantly more polished across both interface themes.