Arnav Kumar

Posted on Feb 14, 2022 • Edited on Feb 16, 2022

Using Dark/Light Mode Specific Images in GitHub Markdown

#github #darkmode #theme #markdown

Hey There Devs! 👋

Hope you are doing great with your projects.

Why this post? 🤔

As a developer we develop projects, write code all day around and we might also publish it on GitHub to let others understand and use our project.

And Markdowns play a vital role in explaining the code, branding your projects, showcasing your stats and so on.

And you all know how much is the craze of the Dark Mode nowadays especially between the Devs. But most browsers have light mode as their default.

So, here comes the actual point of this post. By default GitHub adapts most of the parts of the Markdown according to the theme. But it doesn't do anything with your images by default.

Imagine an image that was made to look good on white background with black as its foreground color. it will not even be notable in the dark mode.

So, you may want to optimize your Images according to the current theme of the viewer's browser. And also maybe to look a bit cool and professional 😅.

Procedure 🧪

The procedure is very simple. No I am not joking its actually very simple.

Do Create 2 separate versions of your images one optimized for light mode and one for dark mode. For example take this image of Termux. I have created two variants of the same image, one for light and one for dark:
Light Mode Variant

Dark Mode Variant
Now, here comes the magical thing 🪄. To make an Image only visible in Dark Mode, add #gh-dark-mode-only at the end of the image url. And to make an Image Only Visible in Light Mode, add #gh-light-mode-only.

Example:



![Termux Logo](https://user-images.githubusercontent.com/72879799/153904003-d7dee710-6552-4d23-a803-7a9a0ba67d92.png#gh-dark-mode-only)
![Termux Logo](https://user-images.githubusercontent.com/72879799/153904095-9d78a019-8495-4035-8174-e3da8e4dd66b.png#gh-light-mode-only)

Now the Dark Mode variant of the Image will only be visible in the Dark mode and the Light Mode variant will only be visible in the Light Mode.

The Image URLs above are just for demonstration. Replace them with your own image URLs and you are Ready to Go!

And it works 🥳🎉!

Live Example ⚡:

You can see the working example at my GitHub.

Disclaimers ⚠️

Note that it will not adapt according to the Theme if the image is not hosted on the GitHub

Top comments (40)

Liu Yongliang • Feb 15 '22

That's interesting:)
Did a bit of search online and found the official documentation of this feature here and the discussions leading up to this feature in the community

Arnav Kumar • Feb 15 '22

Thats really nice!

Hope we will be getting somethng like that in dev.to post markdowns too

lionel-rowe • Feb 15 '22

Really not a fan of GitHub's approach here. Markdown is supposed to be a format that's compatible with many platforms, and a valid URL can only have one hash. That means that other platforms either have to implement the URL hash matching logic along with the gh-* names, or they have to implement it in an inconsistent way, such as through query params (https://example.com/img.jpg?gitlab-theme=dark&discourse-theme=dark&some-other-platform=dark#gh-dark-mode-only). Why not just use a single, cross-platform query param (?theme=dark), add this as a documented part of GitHub-flavored markdown, and be done with it? Other platforms that fully or partially support GFM can then add support in their own time, without using up the single "slot" in the URL's hash or using explicitly gh-* named parameters.

Arnav Kumar • Feb 15 '22

I am totally agree with your points here. And also i didn't like how they restricted to the images that are only hosted via github. Ig they did that to overcome that hash issue in urls. They might have thought that if they won't allow any other urls, there won't be any problems in using hash.
tbh its a very bad and untidy approach to simple thing. In my views either the query paramaters are good or specifying them as options like ![Dark](https://example.com/dark_img.png){theme = dark}.

Seems like its time to open an issue at the their support or in the github repo

Arnav Kumar • Feb 15 '22

In the community the actual guy who requested for the feature actually had suggested somewhat better approach but the GitHub doesn't seem to take his suggestions.

lionel-rowe • Feb 15 '22

I guess they are owned by Microsoft now so maybe we shouldn't be surprised by this kind of embrace-extend-extinguish bullshit.

Arnav Kumar • Feb 15 '22

Microsoft keep doing unusual things 😑

Nicolus • Feb 18 '22

To be fair github started using "github flavored markdown" (which basically means that if you clone a repository on any other host your readme.md will not display correctly) loooong before Microsoft every thought about buying them.

lionel-rowe • Feb 18 '22

I'm on board with GFM, especially now it has become a de-facto standard (albeit one among several). Ideally there'd be a proper spec for it, but there isn't one of those even for the original version of Markdown.

The problem with gh-* hash params is that it forces other implementers of GFM to implement this explicitly GitHub-centric API that even end users have to know about. I mean maybe that's intentional from a "branding" point of view, but it's incredibly obnoxious from a design point of view.

Rajnish Anand • Feb 14 '22

Actually i been looking for this. ✨

Arnav Kumar • Feb 15 '22

Pleased to be helpful ❤️

Akin C. • Feb 17 '22 • Edited

Hello Arnav Kumar,

thank you for your article.
I enjoyed reading it and testing what you wrote.
I took two images that let the user know what mode he/she is in.
This is interesting because I'm telling the user what mode he/she is in without me knowing what mode the user is really in :D!