This content originally appeared on DEV Community and was authored by Saurabh Rai
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.
<!-- The light mode image is followed by the dark mode image -->
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 <picture> Element
For a more universal, web-standard solution, you can embed an HTML <picture> element directly into your Markdown file. This method uses the prefers-color-scheme CSS media feature to serve the correct image.
<picture>
<!-- Source for dark mode -->
<source media="(prefers-color-scheme: dark)" srcset="https://path/to/your/image-dark.png">
<!-- Fallback image for light mode and other clients -->
<img alt="My Alt Text" src="https://path/to/your/image-light.png">
</picture>
Pros:
- Web Standard: This approach works in most modern browsers and on any platform that correctly renders HTML within Markdown.
-
More Flexible: The
<picture>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
-
Browser Caching: If you're testing and the image doesn't switch, it might be a caching issue. Try a hard refresh (
Ctrl+Shift+RorCmd+Shift+R) or view the page in an incognito window. - 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.
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.
This content originally appeared on DEV Community and was authored by Saurabh Rai
Saurabh Rai | Sciencx (2025-08-22T02:30:33+00:00) How to display different images for GitHub light mode and dark mode. Retrieved from https://www.scien.cx/2025/08/22/how-to-display-different-images-for-github-light-mode-and-dark-mode/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.