How to display different images for GitHub light mode and dark mode

Learn how to make your images automatically adapt to light and dark themes on GitHub README using Markdown and HTML, especially for company/project logos.

Method 1: The GitHub-Specific URL Fragment

GitHub provides a simple, Markdown-native way to specify theme-based images by appending a fragment to the image URL. You provide two separate images, and GitHub’s frontend displays the appropriate one based on the current theme.

• #gh-light-mode-only
• #gh-dark-mode-only

Here’s how you implement it. Notice you are essentially writing two separate Markdown image links on the same line.

![My Alt Text](https://path/to/your/image-light.png#gh-light-mode-only)
![My Alt Text](https://path/to/your/image-dark.png#gh-dark-mode-only)

Pros:

• Pure Markdown: No HTML required. It keeps your files clean and simple.
• Easy to Remember: The syntax is straightforward and semantic.

Cons:

• GitHub Only: This is a proprietary GitHub feature. It will not work on other Markdown platforms like GitLab, Bitbucket, or most static site generators. But also, you’re doing this for your public GitHub Project.

Method 2: The HTML Element

For a more universal, web-standard solution, you can embed an HTML element directly into your Markdown file. This method uses the prefers-color-scheme CSS media feature to serve the correct image.

  
   media="(prefers-color-scheme: dark)" srcset="https://path/to/your/image-dark.png">
  
   alt="My Alt Text" src="https://path/to/your/image-light.png">

Pros:

• Web Standard: This approach works in most modern browsers and on any platform that correctly renders HTML within Markdown.
• More Flexible: The element can be extended with more sources for different themes, screen sizes, or image formats.

Cons:

• Requires HTML: It introduces HTML into your Markdown.
• More Verbose: The extra syntax/code for just an image. As the number of images grows, the README.md will be bloated.

Common Pitfalls

1. Browser Caching: If you’re testing and the image doesn’t switch, it might be a caching issue. Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or view the page in an incognito window.
2. Unsupported Platforms: Remember that the fragment method is GitHub-specific. If your Markdown is rendered elsewhere, it will likely show both images stacked on top of each other.

References : 1, 2

This blog stems from my need to find a way to render dark/light images on my GitHub project. And I’ll document this for everyone.

Feel free to reach out to me if you have any questions:

DMs are open, and I’m happy to help.