What is GitHub Profile Readme & How to create one?

Jan 13, 2021 by Kolappan N

If you have used GitHub you might have noticed the importance of a Readme file. For those who are unfamiliar, it is the a markdown or a text file whose contents are rendered automatically by GitHub. A Readme file at the root folder of your repo will contain the information that is shown when a user visits your repo. In addition to that any contents of a Readme file in any directory will also be rendered when a user navigates to that directory.

GitHub then took this idea about Readme and expanded it. They decided to bring a Readme to user’s profile so that when someone visits a users profile the contents of that Readme will be rendered. With many developers already using their GitHub profile as a Portfolio, adding a Readme greatly benefits that use case. As markdown supports a lot of things including tables, images, links, lists, code blocks, etc… you can add almost anything from your portfolio into it.

How to create a Readme for your GitHub profile?

  1. Create a repository in GitHub with the same name as your username. If your username is JonSnow then your repository name should also be JonSnow.
  2. Now create a Readme in this repository. This readme is your user profile’s readme. Whatever you type here will be shown in your user profile.

For example the following Readme will be shown as,

- 🔭 I'm Scott Hanselman
- 🌱 I've blogged here for nearly 20 years https://hanselman.com/blog
- 👯 I've podcasted here for 15 years https://hanselminutes.com
- 🤔 I'm on Twitter https://twitter.com/shanselman
- 💬 and I like making YouTubes https://youtube.com/shanselman
- 📫 How to reach me: https://www.hanselman.com/about/
- 😄 Pronouns: he/him/his
- ⚡ Fun fact: I've been using an Open Source Artificial Pancreas 24hrs a day since 2016
![Scotts's github stats](https://github-readme-stats.vercel.app/api?username=shanselman&show_icons=true)

Rendered GitHub Profile Readme
Rendered GitHub Profile Readme

What can you use this for?

You can use the GitHub Readme for various things

You can also use GitHub actions to update content such as List of blog posts automatically.

Further Reading