How to add random images in Github profile page

And other cool things you can add

What is Github personal readme

In this post we are going to see how to add random images in your Github profile readme, but what is “Github profile readme”? Well, basically is a readme that you can use to customize your Github profile page. For example my page is https://github.com/albertodeago but you can go on anyone just by changing the username of this URL “https://github.com/username”.
If you want to dig deeper, nothing is better than the official documentation.
At the end of the post I’ll link also some cool profiles where you can take inspiration from and see other things you can embed.

What we are going to build

We are going to build something (a simple service) that makes possible to embed dynamic images in a Github profile, by dynamic I mean that if you access twice that user profile you are (likely) going to see two different images. For example in mine https://github.com/albertodeago a random xkcd image should appear at the bottom every time you access it (except first time probably, because I’m using a free tier hostng for my Node.js app and that takes some time to wake up).

⚠️ We are going to build a simple service and not something that is ‘production ready’, so there will be a lot of improvable things. Also this tutorial consider that you already know javascript basics and will focus only on creating the service to achieve our goal (I won’t explain how to install dependencies and other javascript details)

How it works

So how can you achieve that? Github offers you just a normal readme to customize your profile that will be transformed into an HTML page (actually with some manipulations, I’ll say something about this later). You sure can add an image with a src that points to an image that you host somewhere (like in Github itself), but that's not going to be dynamic… So the only way (at least that I know) to add a dynamic image in our case is to point the src of an image to a GET service that returns a 'random' image. This way every time a user access the profile page the service returns a different image to the user.

Let’s do it

Enough with the talk, let’s see some code. I will start with the readme that is going to be SUPER simple:

code — readme part

We can see that we just need to add an image pointing to the url of the service that we are going to build now. Really that’s it. Let’s built the service:

code — setup express server

Let’s explain briefly what we’ve done so far. First we import request to make http requests easier, then express (you need to add both as dependencies) and we create an express app, then we add a route random-xkcd that get an image url using the getRandomXkcdImageUrl function (we are going to write this function soon), fetch that image and then respond with that image (with content-type set to image/png (this is to inform the browser that it’s an image) and with a cache-control header set to avoid caching (if we don't set it the browser is going to cache the image and it won't fetch different images on refresh). Last we set the app on listening to wait for requests.

Let’s implement getRandomXkcdImageUrl function, it must return the url of a random xkcd comic:

💡 To implement this we are using the xkcd json API (more info here → https://xkcd.com/json.html)

code to get the URL of an xkcd comic

As we can see this function get a random number (from getRandomXkcdNumber) and uses xkcd API to get the episode related to that number. If we get an error we just return an empty string, otherwise we return the img property of the response (that is the url of the comic, coming from the xkcd API).

Now we just need to implement getRandomXkcdNumber and we have already finished our work.

code to get the number of a random xkcd comic

So here we first fetch the current comic (from http://xkcd.com/info.0.json). If we don't get an error we just read the num property. This will tell us the number of the current episode (and this is the greatest number, xkcd comics are numbered, the first is numbered 0, as any programmer would do). So we can use that number to get a random integer between 0 and the value we got, we then have a small loop to make sure we don't return 404 because that's a special case that is going to return a 404 code from the xkcd API instead of a comic. Then we just return that number.

Wrapping up

So the entire code can be found in this repository, you just need to host this somewhere, for example in AWS, Heroku or Glitch and use the url of the service deployed in the Github readme (I won’t explain how to host it because the article would become too long, but the official documentation of these services are a very good start to deep dive in).
Just keep in mind that if you use a service like Heroku with free tier sometimes the image won’t show up in the profile page because of the server startup time (free tiers usually fire up the server only when it actually needs, so when someone makes a request to it and they take a bit of time, like 15–30 seconds).

I tried to mitigate this but I failed to do so. I wanted to create a fallback image in case of loading error but that seem impossible in the Github profile.

I’ve found a way to create a pure HTML image fallback but it doesn’t work on Github because the page is being changed by Github itself (he will strip a lot of things, scripts for example and other tag and attributes for security reasons).
If you are interested in this I’m going to write an article about that fallback soon because it seems to be a bit obscure as fallback (spoiler, it uses the object tag, so it's a bit weird indeed).
If you have an idea (or even better a solution) for the image fallback, please reach out to me on my twitter or leave a comment here

Other cool things you can add

You can build various services similar to this to display different dynamic content.
But you can also enrich your profile with other cool things. Here is a list of cool profiles that I’ve seen:

• Swyx has a cool profile, also he’s pretty amazing, I highly suggest you to follow him
• bdougie shows the latest followers (using Github actions)
• timburgan let you play chess on his profile, this is crazy
• DoubleGremlin181 a guy let you play tic tac toe
• DenverCoder1 has a lot of things (and mostly dynamic)
• fnky this is one of my favourites… Look at that retro feel

If you want to see more and also explore tools to help you customize your profile awesome github profile repository is the best place to go.