Cover image for How To Create A GitHub Profile README

How To Create A GitHub Profile README

m0nica profile image Monica Powell Updated on ・3 min read

GitHub recently released a feature that allows users to create a profile-level README to display prominently on their GitHub profile. This article walksthrough how to access this new feature. I'll also be sharing some fun GitHub profiles I've seen so far. I'd love it if you shared yours with me on Twitter @waterproofheart.
The header GIF shows what my README looks like at the time of this writing. You may notice I was recently selected to be GitHub star!


The GitHub profile-level README feature allows more content than the profile bio, supports markdown which means you can play around with the content more visually (Did someone say GIFs!?) and the README is significantally more visible as it is placed above pinned repositories and takes up as much space above the fold of the webpage as you like.

A solid README is a core-component of well-documented software and often encourages collaboration by sharing helpful context with contributors. In my opinion, a profile-level README seems like a great extension of a convention a lot of GitHub users are already familiar with. If you're looking to make project-level READMEs more awesome and helpful check out matiassingers/awesome-readme for resources and examples of compelling READMEs.

How do I create a profile README?

The profile README is created by creating a new repository that’s the same name as your username. For example, my GitHub username is m0nica so I created a new repository with the name m0nica. Note: at the time of this writing, in order to access the profile README feature, the letter-casing must match your GitHub username.

If you already have a project in a repo-named username/username and are interested in setting up a profile-level README, then I recommend either re-naming that repository or re-purposing the existing project's README based on what makes the most sense in your particular situation.

  1. Create a new repository with the same name (including casing) as your GitHub username: https://github.com/new

  2. Create a README.md file inside the new repo with content (text, GIFs, images, emojis, etc.)

  3. Commit your fancy new README!

    • If you're on GitHub's web interface you can choose to commit directly to the repo's main branch (i.e., master or main) which will make it immediately visible on your profile)
  4. Push changes to GitHub (if you made changes locally i.e., on your computer and not github.com)

screenshot of the GitHub page for creating new repositories


The GitHub README profiles are written in Markdown which means you aren't just limited to texts and links, you can include GIFs and images. Need to brush up on Markdown Syntax? Check out this Markdown Cheatsheet.

If you're really ambitious you can use GitHub actions or other automation like bdougieYO or simonw to dynamically pull data into your README:

Serverless functions can also be used to dynamically generate information (for example your current Spotify activity):

I'm a huge proponent that folks should maintain a website they have complete ownership over (even if it's a no-code website solution) but this is tempting...

I've been inspired by the creative READMEs I've seen so far and am looking forward to seeing all kinds of profiles in the upcoming months.

Posted on by:

m0nica profile

Monica Powell


Hi, I'm Monica! I'm a product engineer who is building technology to elevate people and is currently focusing on growing the React Ladies community for React developers.


markdown guide

I have created Developer Profile repository with a bunch of GitHub profiles so that others will get inspiration to create their own. Do consider to contribute with your profile also.


Only downside I can see to this is that the README seems meant to be a living document. Mine is a bunch of gifs now, but later I could update it to actually be professional or something and less awesome.


You may update it later in the repo also.

I see screenshots got added recently, nice! :)


I saw someone post theirs the other day with a fun animation. I hadn't realized this was a new feature so I thought they were just joking around. But this is great! I'm going to have to do some brainstorming on mine. Maybe I'll see how much of my design skills I can use in it as well!


I've set mine up to automatically pull in my latest uploads from YouTube, using a Netlify Serverless function:


Tired of updating GitHub profle README with latest features again & again?

If yes, then I have developed a tool to do the same for you in just 1 click πŸ€“

πŸš€ Try the tool: live tool

If you find the tool useful, show some love by giving a ⭐ on github repo

GitHub logo rahuldkjain / github-profile-readme-generator

πŸš€ Generate github profile README easily with latest add-ons like visitors count, github stats, etc using minimal UI.

Github Profile Readme Generator

Github Profile Readme Generator

github-profile-readme-generator licence

github-profile-readme-generator gif

Tired of editing Github Profile README with new features?

This tool provides an easy way to create github profile readme with latest addons like visitors count, github stats etc.

πŸš€ Try it out: Live demo

🧐 Features

Just fill the details like Name, Tagline, Dev Platforms Username, Current Work, Portfolio, Blog etc. with a minimal UI.

Click on Generate README to get your README in markdown. You can preview the README too.

You can add latest addons like visitors count, shields, dev icons, github stats etc to your README in just one click.

Designed with πŸ’« by Rahul


You inspired me to make my own readme and make this open source project #justforfun that allows you to generate github readme files: arturssmirnovs.github.io/github-pr...


Here's mine which shows your latest medium blogs.

checkout my repo github.com/harshalrj25/mediumblog-... to add medium blogs to your profile.


This feature may be that solution for

  • a website (sort of); a win-win for you if you
  • write your blogs in markdown, push to GitHub and publish on dev.to,,
  • one more thing, custom domain.

Thanks for sharing Monica!


Hi! Do you know if this is also available to organizations?


I think the simplest profile page is mine.

That's all it takes when you're not a developer :)


I have created a repository for awesome github profile aims to collect the all awesome beautiful READMEs profile and make your Profile look good & Inspire other's.


Not wanting to plug my self but I think my profile also looks pretty nice and has a few easter eggs:


Hi there πŸ‘‹

I am aayushi Sharma. I Love ❀️ programming and currently working as Machine learning engineer.

Language & Skills

  • Python
  • C++
  • JavaScipt
  • Web Development
  • Machine Learning
  • Deep learning
  • Natural language processing
  • App Development

Things got bugs, gonna smash them one by one



What a nice feature!

This is going to my to-do for future build!

Thanks πŸ‘


I made mine after seeing this post thanks a lot.

My Readme : Profile


This inspired me to make my own Github readme profile.
Thx for the same :)
Here's the link : Github


pretty cool, I did not pay attention to that before, thanks for sharing


Now GitHub is my dream destination! 😌


Have a look at mineπŸ˜πŸ‘‹.

GitHub logo 8bithemant / 8bithemant

Github README.md. Consists of Lot of Badges, git, png, and a lot of Love, Live Github Stats. Add this to your profile and help me with contributing to this stuff. Github Profile README.md

Hi there, I'm Hemant! πŸ‘‹.

Hemant Joshi| Twitter Linkedin Telegram Instagram  Reddit Leetcode  Codechef


Hi πŸ™‹β€β™‚οΈ,

I'm 18 years old Self-taught Full-Stack developer from India.

- πŸ₯€ Learning GraphQl ,NextJs &Typescript .

- πŸ”­ SpaceX FanBoi,

- πŸ›Έ Into High Energy Physics and Astrophysics

- πŸ’¬ Connect? Here πŸ‘‰πŸΌ

I am Into , πŸ™

Machine Learning, Web Development, SEO, Micro Services, System Design, Competetive Programming & Physics and Physics 😼

Github Stats By Anurag

- Languages and Tools...

html csharpjspythonreactvuechromeclouddatascienceawsnpmgcpbashvscode

- Blogs 🌱

- Podcast ⚑️

Thank You-πŸ™πŸΌ


Have a look at mine ✨

I use a fancy fonts style



My profile: yourls.fxgit.work/a005

Learn to use GitHub for Python and send Actions to Telegram Bot.


python #telegram


This is such an underused feature. Thanks for sharing it!


Great Article!

Just want to share this to add some details for the Github README profile πŸ˜„




Is there any way in markdown to do a responsive image (ie. different images for different widths)?

You can use an img tag in GitHub markdown, but it doesn't support srcset.


Here is mine. How's It.
If anyone needs source code, fork it.

Hi πŸ‘‹, I'm Codeperfectplus


Skilled in Data Science, Machine Learning, Deep Learning, As Well As Basic Basic Web Development Knowledge. Strong professional with a Master's Diploma in Data Science.

react css3 django docker html5 typescript postgresql python


codeperfectplus codeperfectplus codeperfectplus codeperfectplus


Haha how can I not follow this trend, here is mine. :) Made with animated svg!

annie taylor chen github readme profile


Thanks for the steps to be followed ans also the exemples.