🍿 3 min. read

How To Create A GitHub Profile README

Monica Powell

GitHub recently released a feature that allows users to create a profile-level README to display prominently on their GitHub profile. This article walks through 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 @indigitalcolor.

The above 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 significantly 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.

  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)


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.

This article was published on July 11, 2020.

Don't be a stranger! 👋🏾

Thanks for reading "How To Create A GitHub Profile README". Join my mailing list to be the first to receive my newest web development content, my thoughts on the web and learn about exclusive opportunities.


    I won’t send you spam. Unsubscribe at any time.


    • shelby spees is staying home 😷
    • Berl
    • Louis Offor
    • Jason Burkert
    • Hashim Warren 🧑🏾‍🚀
    • Jimmy Millard
    • Jonathan Lurie
    • The sixth Otu
    • ♫Yani♀
    • Jen Gentleman 🌺
    • Jewel Barnett, Ph.D.
    • Elisabeth Hocke
    • Cheryl A
    • Jeremy Booker
    • Jython Jangle
    • Pachi - she/her/ela #BLM
    • Jeremy Abbott 🏳️‍🌈🧙🏼‍♂️
    • Meghan Martin
    • {{Neil Coutinho}}
    • minkiu
    • Chris 🦉🦉
    • David Borg
    • Joson Lim 림택용 🇸🇬
    • Amit
    • Matthias Ott
    • ragul
    • Birnur Uzun
    • Gilbert - Señor Systems Engineer
    • m̴̧͇͈̫͈̈͑̓̏͘i̴̧̯̪̗̍̎̊͗͜͝k̸̢̲̪̳̰͗̇̒̑̚e̵̡̖̼̦̘͒̊̍͐͘y̷
    • Adonis, The Backend King
    • Bartosz Cytrowski
    • cookey
    • Jessica Leiria Schattschneider
    • Einzig Dave
    • Kate Kourbatova
    • Patrick Eronmwonse Ogbekhilu
    • Christiane Celeste
    • Gabriel 🍃
    • Marvin Tunji-ola
    • фронт енд мудолопер
    • +1846