Improving Your GitHub Profile with Profile READMEs

Source: GitHub | Kinsta

Today we will be going over a very overlooked feature that GitHub has. The feature I'm talking about is a profile README. What is a profile README you ask? Well, it is ultimately a README file like in any repository, but it is displayed on your profile page within GitHub. This means that it will be publicly viable by anyone that goes to your profile!

In this article, we will be going over why we even care about creating one, actually creating one, and then taking a look at some of the possibilities.

1. Why Create a GitHub Profile README

Why do we care about a feature like this? Well, it allows your profile to stand out from others and also allows you to express yourself on your profile page. Similar to a project README, a profile README can tell visitors all about you and what you have to offer. This can be beneficial if you use your profile as a portfolio for your projects or if you just wish to tell others about yourself.

Here is an example of what one looks like:

My GitHub Profile README

It’s nothing to brag about, but mine is fairly simple compared to others. It has my information at the top, runs a GitHub Action to pull and display my latest blogs here on Medium, and then a card that displays my public GitHub stats.

Depending on what your goal is, you can make your profile README do all sorts of things.

2. How to Create One

Creating one is super simple. All you need to do is create a public repository that is the same name as your username and add a README file to it.

Creating the repository.

If everything was done correctly, you should get a popup that says you have found a secret!

From here all you need to do is update that, push it to the designated main branch, and it should show on your profile page! Super simple isn’t it?

3. Community READMEs

So now that we are done with creating the repo, this is where GitHub profile READMEs get fun. Since it’s just a Markdown file at the end of the day, you can add gifs, images, links, basically anything you want at this point. If you need a reference for Markdown, check out GitHub’s guide on it.

If you want to take it one more step further, GitHub Actions allow you to create interactive profiles. This can be something as simple as pulling in the latest blog posts from Medium, your latest videos from YouTube, or even displaying the current song you are listening to on Spotify.

Here is a community list of pretty awesome and neat READMEs:


I barely scratched the surface when it comes to profile READMEs. There is so much you can do with them and I’m always fascinated by what the community creates.

For my specific README, it can be found here:

See you guys in the next one!

Senior Software Engineer Consultant at Liferay. Passion for learning, teaching, and creating cool software tools for others to enjoy.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store