How to make an astounding and elegant GitHub profile README
Step-by-step beginner’s guide to create your GitHub profile README
The README file is crucial to present an effective overview of your projects. It is the first thing a potential employer sees if they visit your repository. That is why I’m doing this guide series on how to make your GitHub stand out using the READMEs.
In 2020 GitHub added a (hidden?) feature in which you can create a special README to show in your profile page. And that is the focus of this article, I will show you the process of how to create it as simple as it is. At the end, I will share some resources for your inspiration.
This is first part of the two-part guide, the second one will be about the README file of the actual repositories.
The first step is to create the repository at https://github.com/new. The name of the repo must be the same as your username. In my case is dewith/dewith. And don't forget to initialize the repo with a README file.
Once you have created the repository and clicked "Edit README", you should see something like this:
We will use GitHub's interface to edit the README, since it is not necessary to clone the repository on your local machine.
I'm going to show you how to recreate the README of my profile, but I encourage you to create something more personal once you get the idea.
TL;DR. Just show me the code!
This tutorial is made for beginners so I've written below a detailed explanation for every part of the code. Yet, if you're not a beginner, here's the entire code:
<h1 align="left"> Hey there, I'm Dewith 👋 </h1>
<p align="left">
<a href="https://dewith.co/"><img alt="Portfolio" src="https://img.shields.io/badge/-dewith.co-black?style=flat-square&logo=squarespace&logoColor=white&link=https://dewith.co/"></a>
<a href="https://www.linkedin.com/in/dewithmiramon/"><img alt="LinkedIn" src="https://img.shields.io/badge/-dewithmiramon-black?style=flat-square&logo=Linkedin&logoColor=white&link=https://www.linkedin.com/in/dewithmiramon/"></a>
<a href="https://twitter.com/DewithMiramon"><img alt="Twitter" src="https://img.shields.io/badge/-@DewithMiramon-black?style=flat-square&logo=twitter&logoColor=white&link=https://twitter.com/DewithMiramon"></a>
<a href="mailto:dewithmiramon@gmail.com"><img alt="Gmail" src="https://img.shields.io/badge/-dewithmiramon@gmail.com-black?style=flat-square&logo=Gmail&logoColor=white&link=mailto:dewithmiramon@gmail.com"></a>
<a href="https://medium.com/@dewith"><img alt="Medium" src="https://img.shields.io/badge/-@dewith-03a57a?style=flat-square&color=000000&labelColor=000000&logo=Medium&link=https://medium.com/@dewith"></a>
</p>
<h3 align="left"> I'm an industrial engineer who is interested in data analytics and applied machine learning. Enthusiast of graphic design and illustration. Internet citizen. </h3>
---
<!-- credits for gif https://gph.is/g/ZWg5jr7 -->
<img align="right" height="150" width="210" src="data.gif">
- 🔭 **I’m currently working on:** ML models
- 🌱 **I’m currently learning:** data engineering
- 👯 **I’m looking to collaborate on:** data science projects/competitions
- 💬 **Ask me about:** data science, memes, kdramas, Bad Bunny
- ⚡ **Hobbies:** books, internet, music, series, pet my cat
- 😄 **Pronouns:** he/him
---
<a href="https://dewith.co/"><img height="150px" src="https://github-readme-stats.vercel.app/api?username=dewith&show_icons=true&hide_title=true&hide_border=true&theme=graywhite" /><img height="150px" src="https://github-readme-stats.vercel.app/api/top-langs/?username=dewith&show_icons=true&layout=compact&langs_count=6&hide_title=true&hide_border=true&theme=graywhite" /></a>
Heading & subtitle
Usually, the title is a greeting with your name. And the subtitle it's a brief text which contains: what do you do, where do you work, or where are you from. It's up to you what to state here.
I used HTML for this part because it provides more options than Markdown (custom align, for example). I prefer it left aligned, but centered looks great too.
<h1 align="left"> Hey there, I'm Dewith 👋 </h1>
<h3 align="left"> I'm an industrial engineer who is interested in
data analytics and applied machine learning. Enthusiast of
graphic design and illustration. Internet citizen. </h3>
Note that I don't use a normal text for the subtitle, but an H3 tag. I think it helps the subtitle to stand out from the rest of the text.
Social media
Between the title and the subtitle, I placed the social media links because I want them to be as more accessible as possible.
The social badges are from shields.io project. Every badge is composed of two things:
- The hyperlink (the <a> tag)
It has the URL to which the badge will direct. - The badge image (the <img> tag)
This will contains the image that markdown will show. It must be placed inside the <a> tag.
An entire badge will look like this:
<a href="https://www.linkedin.com/in/dewithmiramon/"><img alt="LinkedIn" src="https://img.shields.io/badge/-dewithmiramon-black?style=flat-square&logo=Linkedin&logoColor=white&link=https://www.linkedin.com/in/dewithmiramon/"></a>
All you have to change is the href attribute with your LinkedIn profile link and the text of the badge in src after https://img.shields.io/badge/-.
I kept all my badges monochromatic for the ✨ aesthetics ✨ but you can change the colors to the platforms' originals if you want to. I'll leave both versions.
Black version
<p align="left">
<a href="https://dewith.co/"><img alt="Portfolio" src="https://img.shields.io/badge/-dewith.co-black?style=flat-square&logo=squarespace&logoColor=white&link=https://dewith.co/"></a>
<a href="https://www.linkedin.com/in/dewithmiramon/"><img alt="LinkedIn" src="https://img.shields.io/badge/-dewithmiramon-black?style=flat-square&logo=Linkedin&logoColor=white&link=https://www.linkedin.com/in/dewithmiramon/"></a>
<a href="https://twitter.com/DewithMiramon"><img alt="Twitter" src="https://img.shields.io/badge/-@DewithMiramon-black?style=flat-square&logo=twitter&logoColor=white&link=https://twitter.com/DewithMiramon"></a>
<a href="mailto:dewithmiramon@gmail.com"><img alt="Gmail" src="https://img.shields.io/badge/-dewithmiramon@gmail.com-black?style=flat-square&logo=Gmail&logoColor=white&link=mailto:dewithmiramon@gmail.com"></a>
<a href="https://medium.com/@dewith"><img alt="Medium" src="https://img.shields.io/badge/-@dewith-03a57a?style=flat-square&color=000000&labelColor=000000&logo=Medium&link=https://medium.com/@dewith"></a>
</p>
Colorful version
<p align="left">
<a href="https://dewith.co/"><img alt="Portfolio" src="https://img.shields.io/badge/-dewith.co-orange?style=flat-square&logo=squarespace&logoColor=white&link=https://dewith.co/"></a>
<a href="https://www.linkedin.com/in/dewithmiramon/"><img alt="LinkedIn" src="https://img.shields.io/badge/-dewithmiramon-0075b5?style=flat-square&logo=Linkedin&logoColor=white&link=https://www.linkedin.com/in/dewithmiramon/"></a>
<a href="https://twitter.com/DewithMiramon"><img alt="Twitter" src="https://img.shields.io/badge/-@DewithMiramon-08a0e9?style=flat-square&logo=twitter&logoColor=white&link=https://twitter.com/DewithMiramon"></a>
<a href="mailto:dewithmiramon@gmail.com"><img alt="Gmail" src="https://img.shields.io/badge/-dewithmiramon@gmail.com-eb4336?style=flat-square&logo=Gmail&logoColor=white&link=mailto:dewithmiramon@gmail.com"></a>
<a href="https://medium.com/@dewith"><img alt="Gmail" src="https://img.shields.io/badge/-@dewith-51a652?style=flat-square&logo=Medium&logoColor=white&link=https://medium.com/@dewith"></a>
</p>
If you need to add a different badge here, search for posts or tutorials on how to make custom badges. I'll list some resources I found useful:
- List of Badges, in Markdown
- How To Make Custom Language Badges for your Profile using shields.io.
- How to make custom badges to improve your Markdown documents
Quick information
This part is to let people know you better. The standard items are:
- 🔭 I’m currently working on ...
- 🌱 I’m currently learning ...
- 👯 I’m looking to collaborate on ...
- 🤔 I’m looking for help with ...
- 💬 Ask me about ...
- 📫 How to reach me: ...
- 😄 Pronouns: ...
- ⚡ Fun fact: ...
Of course, you can delete some of them or add your own.
On this part I added a gif on the right side to give some freshness and motion to the page. All you have to do is to download a cool gif from Giphy or Tenor. If I were a developer, I would choose this one 🐶
Image by After you choose a gif, upload it to the repo. I saved mine with the filename data.gif.
And this is the final code:
---
<!-- credits for the gif https://gph.is/g/ZWg5jr7 -->
<img align="right" height="150" width="210" src="data.gif">
- 🔭 **I’m currently working on:** ML models
- 🌱 **I’m currently learning:** data engineering
- 👯 **I’m looking to collaborate on:** data science projects/competitions
- 💬 **Ask me about:** data science, memes, kdramas, Bad Bunny
- ⚡ **Hobbies:** books, internet, music, series, pet my cat
- 😄 **Pronouns:** he/him
---
Stats widgets
And the final part is the GitHub stats widgets. This project was made by anuraghazra, you can take a look at his repo. These widgets are dynamically generated based on your commits, issues, stars, language usage, etc.
What I like the most of these widgets is all the customization possible. Again, I chose a simple theme because I like minimalist stuff, but you can choose yours from the dozens of themes it provides.
<a href="https://dewith.co/"><img height="150px" src="https://github-readme-stats.vercel.app/api?username=dewith&show_icons=true&hide_title=true&hide_border=true&theme=graywhite" /><img height="150px" src="https://github-readme-stats.vercel.app/api/top-langs/?username=dewith&show_icons=true&layout=compact&langs_count=6&hide_title=true&hide_border=true&theme=graywhite" /></a>
As you can see, you can customize a lot in the URL: show_icons, hide_title, hide_border, theme, and many others.
If you want the widgets to redirect to your website or to something else, make sure to leave the widgets inside the href of the tag as I do.
If you followed all the steps...
Profiles for design inspiration
My readme ain't much, but it's honest work. And I say it because I've seen impressive profiles, but they are as sophisticated as they are complicated to recreate. But it's up to you how much time and effort you put into building your profile.
There are many collections of GitHub profiles READMEs out there. I will give you two of them that have the profiles categorized, so it is easier to find inspiration.
Hope you find useful this tutorial, don't forget to visit the part II (I'll leave the link here once it's ready).
Please, don't hesitate to leave a comment about any doubt or question you have about the process.
Later!