DEV Community

Cover image for How to create a GitHub Profile README
Michelle Mannering for GitHub

Posted on • Updated on

How to create a GitHub Profile README

We launched GitHub Profile READMEs last year and developers have been loving this feature.

When we launched the Profile README, we put out a short clip letting you know how to create yours.

Since then, I'm constantly getting asked on my live streams for templates, tutorials, and ideas on setting up your profile. So I thought I'd write down some ideas, as well as snippets of code you can use.

Step 1. Creating your Profile README

Before we jump into the steps on how to create a Profile README, check out mine for inspiration:

👋 Hey everyone, I'm MishManners®™ AKA the Hackathon Queen®™ 👋

mishmanners gaming room - gif of my actual gaming room setup

👋 Hi, I'm a multi-talented personality in the tech and gaming communities. As a developer advocate 🥑, I get to share my knowledge and experience through articles, presentations, and even Twitch streams. I have written articles on technical topics, and spoken at conferences and events on the importance of collaboration, community building, and the future of work. I'm also a respected leader in the hackathon community, having won, organised, and mentored at numerous events. I'm a successful entrepreneur and founder, having co-founded several companies – including an artificial intelligence company. You'll often catch me at an event, speaking on stage, or on a live stream!

And yes my name was Michelle "MishManners" Mannering, and now I am Michelle "MishManners" Duke after getting married in December 2023. We couldn't be happier. You might even catch my player 2 on a live…

I'll be sharing ideas and code snippets from my profile.

To setup your profile, you'll first need to create a special README repo:

  1. Log into GitHub and go to your profile
  2. Click on "Repositories"
  3. Click "New"
  4. Make your repositories name the same as your username
  5. Ensure your repo is set to "Public"
  6. Check the box that says "Add a README file"
  7. Click "Create Repository"

SpecialRepoCreate

You should have a cool green box that says that repo "is a special repository".

Special Repo

Now it's time to customise and personalise your Profile README.

Step 2. Customising your Profile

Firstly, you'll want to think about the types of things you want in your profile. Do you want gifs or images? What kind of information do you want to showcase? Do you want to talk about yourself, your projects, or your work?

It's often a good idea to map out a bit of a plan before you jump into creating your profile - even if that plan is only in your head! 😏

Adding images and gifs

Images and gifs are a great way to embed some flair into your profile. They are also super easy to add. You can now drag and drop a gif or image directly into markdown.

If you'd like a little more control over your image however, use this snippet of code:

<a href="URL_REDIRECT" target="blank"><img align="center" src="URL_TO_YOUR_IMAGE" height="100" /></a>

Here's what each of the elements do:

  • a href allows you to link to any URL. If you don't want to link to anything, you can remove the href if you like, or just leave the URL blank and you can come back to it later.
  • target="blank" means the URL you linked to above will open in a new tab.
  • img align="center" will make your image justified to the center. You can use "left" or "right" too.
  • src is the URL where your image can be found. You can make this a public URL, but I highly recommend uploading your image to GitHub as you can guarantee your image will always live at that URL.
  • height is the height of your image. You can also use "width". The height or width is useful for ensuring all your images have the same dimensions.

Copy and paste the code snippet above and add in the URL to your image or gif. Now you have some cool images on your profile.

Where to find social icons

Speaking of cool images. You might have noticed a lot of people have some pretty slick looking social icons on their profile. Mine for example has a bunch of sleek social media and gaming icons.

Social icons

Where can you find these? There are a couple of places to look:

  • Simple Icons are a really good place to start. They have hundreds of free vector icons and they are always updating them. Plus it's all open source!
  • Flaticon has a lot more coloured icons to choose from. There are various artists here so you'll find that not everything has the same style or is 'official'. Since these are made by artists, you'll need to credit the creator of the icon, unless you pay a premium.
  • Icons8 is similar to Flaticon. Again, if you are using artist created icons, you'll need to credit the designer.
  • Wikimedia Commons is great if you're looking for the official icons, free of charge. They have thousands of free, official logos that are part of creative commons. For example this is the search result for "Xbox logo".

Adding GitHub stats

Okay so you have some awesome pictures, links, and social media icons. But what about all those cool GitHub charts you might have seen floating around?

Stats

These are really easy to setup thanks to the open source people who created them. Firstly, there's the GitHub README Stats by Anurag Hazra.

GitHub logo anuraghazra / github-readme-stats

⚡ Dynamically generated stats for your github readmes

GitHub Readme Stats

GitHub Readme Stats

Get dynamically generated GitHub stats on your READMEs!

Tests Passing GitHub Contributors Tests Coverage Issues GitHub pull requests OpenSSF Scorecard

View Demo · Report Bug · Request Feature · FAQ · Ask Question

Français · 简体中文 · Español · Deutsch · 日本語 · Português Brasileiro · Italiano · 한국어 · Nederlands · नेपाली · Türkçe

Please note that documentation translations may be outdated; try to use English documentation if possible.

Love the project? Please consider donating to help it improve!

Give india logo

Are you considering supporting the project by donating to me? Please DO NOT!!!

Picture of Coromandel Express train tragedy

India has recently suffered one of the most devastating train accidents, and your help will be immensely valuable for the people who were affected by this tragedy.

Please visit this link and make a small donation to help the people in need. A small donation goes a long way. ❤️

Features

The README contains lots of information on setting up the stats, how to display them, and what themes are available. You can choose to use GitHub stats, pins, top languages, and daily stats. For mine, I added in the src to control the width of the image:

<img src="https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=ADD_THEME_HERE" width="400">

If you want to add the GitHub streak to your profile, then head on over to GitHub README Streak Stats.

Streak

You can put your username directly into this website and you'll receive the code snippet to add to your profile. Go and check out the repo for more info on how to customise this one.

GitHub logo DenverCoder1 / github-readme-streak-stats

🔥 Stay motivated and show off your contribution streak! 🌟 Display your total contributions, current streak, and longest streak on your GitHub profile README

Github Readme Streak Stats

Display your total contributions, current streak
and longest streak on your GitHub profile README

⚡ Quick setup

  1. Copy-paste the markdown below into your GitHub profile README
  2. Replace the value after ?user= with your GitHub username
[![GitHub Streak](https://streak-stats.demolab.com/?user=DenverCoder1)](https://git.io/streak-stats)
Enter fullscreen mode Exit fullscreen mode
  1. Star the repo 😄

Next Steps

Deploy to Heroku Deploy to Vercel

⚙ Demo Site

Here you can customize your Streak Stats card with a live preview.

https://streak-stats.demolab.com

Demo Site

🔧 Options

The user field is the only required option. All other fields are optional.

If the theme parameter is specified, any color customizations specified will be applied on top of the theme, overriding the theme's values.

Parameter Details Example
user GitHub username to show stats for DenverCoder1

Adding your GitHub Skyline

Lots of people have seen this on my GitHub profile and have asked how to get it:

Head over to the GitHub Skyline page, and enter your username and select the year. If you like, turn off the UI by hitting the eye in the bottom right corner: eyes

Then use your favourite gif recorder to grab a short screen capture of your GitHub Skyline. If you don't have a favourite, check out my article on using ScreenToGif:

Other elements

There are a lot of really cool tutorials out there on customising profiles. This one from Supritha has a lot of fun ideas in it. You can search around for more awesome ideas. You'll find posts here on DEV, YouTube, Twitter, and more.

Another really cool way to find what to use on your profile is simply by browsing GitHub. Look around at other people's profiles. If you see something you like, check out their README file and see how they created it. There are so many creative things you can do, you just need to get started. Then you can continue adding amazing elements once you find them.

If you liked this article, don't forget to read up on last week's tutorial. I did a short write up on how to add Actions to your profile.

You also might like to brush up on some of the GitHub-Flavoured Markdown changes I dove into a few weeks back:

Top comments (10)

Collapse
 
jasonlong profile image
Jason Long

Shamelessly sharing mine since I had fun building it recently w/ an animated SVG, a weather API, and GitHub Actions: github.com/jasonlong

Collapse
 
snikhill profile image
Nikkhiel Seath • Edited

I really like how you have used workflow to automatically update your README.

Collapse
 
snikhill profile image
Nikkhiel Seath

Following your suit, here is mine: github.com/SNikhill
Not nearly as impressive but, still works. :)

Collapse
 
rohan2734 profile image
rohan2734

can you share other such profile intros animations which will look great?

Collapse
 
rohan2734 profile image
rohan2734

Looking to create an awesome github profile, do you guys have any animations for crisp profile intro which will look great ?

ex: github.com/jasonlong

Collapse
 
denvercoder1 profile image
Jonah Lawrence

Thanks for the mention! Happy to see Github Readme Streak Stats included here 😀

Collapse
 
arshsahzad profile image
Arsh Sahzad

I had fun building too, here is mine: github.com/arshsahzad

Collapse
 
armaaniii profile image
Armaan Choudhary
Collapse
 
itsmeabela profile image
Abel Sintayehu

Am starting out on GitHub I been learning my computer science but I guess am doing good here mine: github.com/a3ela/a3ela/blob/main/R...

Collapse
 
zeynabmvs profile image
Zeynab Movasaqpoor

It was fun customizing my profile, Here is mine: github.com/zeynabmvs