DEV Community

loading...
Cover image for How To Create A GitHub Profile README

How To Create A GitHub Profile README

m0nica profile image Monica Powell Originally published at aboutmonica.com 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!

Why READMEs?

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

Fun READMEs

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.

Discussion (49)

pic
Editor guide
Collapse
coderjojo profile image
coderjojo

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.

Collapse
itsasine profile image
ItsASine (Kayla)

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.

Collapse
coderjojo profile image
coderjojo

You may update it later in the repo also.

Thread Thread
itsasine profile image
ItsASine (Kayla)

I see screenshots got added recently, nice! :)

Collapse
sarehprice profile image
Sarah Price

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!

Collapse
ayushkumar25 profile image
Ayush Kumar


My Github.
For more cool templates.

Collapse
jacques_blom profile image
Jacques Blom

I've set mine up to automatically pull in my latest uploads from YouTube, using a Netlify Serverless function:
github.com/jacques-blom
screenshot

Collapse
shadowscientist profile image
Shadow Scientist

Wow! that's great!

Collapse
vadorequest profile image
Vadorequest

Just built mine in 2h time really quickly, with github stats, trophies, SO feed, medium feed, etc.

github.com/Vadorequest

Thanks to github.com/rahuldkjain/github-prof... which helped me bootstrap real quick!

Collapse
rahuldkjain profile image
Rahul Jain

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 the 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 forks github-profile-readme-generator stars github-profile-readme-generator issues github-profile-readme-generator pull-requests join discord community of github profile readme generator

github-profile-readme-generator gif

View Demo · Report Bug · Request Feature

Loved the tool? Please consider donating 💸 to help it improve!

sponsor github profile readme generator Buy Coffee for rahuldkjain Buy Me A Coffee

Tired of editing GitHub Profile README with new features? This tool provides an easy way to create a GitHub profile readme with the latest add-ons such as visitors count, github stats, etc. 🚀 Demo

Try the tool: GitHub Profile README Generator

🧐 Features

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

  • Uniform Dev Icons

  • Uniform Social Icons

  • Visitors Counter Badge

  • GitHub Profile Stats Card

  • GitHub Top Skills

  • GitHub Streak Stats

  • Dynamic Dev(.)to Blogs (GitHub Action)

  • Dynamic Medium Blogs (GitHub Action)

  • Dynamic Personal Blogs from RSS Feed (GitHub Action)

  • Wakatime Stats contribute

  • Buy Me A Coffee button

Click on Generate README to get your README in markdown

Collapse
sanchitbajaj02 profile image
Sanchit Bajaj

It's great and easy to use

Collapse
israelias profile image
Joem Elias Sanez

Great piece. Newbie, but took a friendly first pass at this — bonus CV frontier!
mine

Collapse
punitkmryh_93 profile image
Collapse
shadowscientist profile image
Shadow Scientist

Nice! I love that illustration! are you a Dribbbler?

Collapse
harshalrj25 profile image
harshal jadhav

Here's mine which shows your latest medium blogs.
harshalrj25

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

Collapse
10secondsofcode profile image
Elango Sundar

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.

Collapse
arturssmirnovs profile image
Arturs Smirnovs

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...

Collapse
imshravan profile image
Shravan Kumar B

Hi, do check this project, to beautify your profile readme. Star it, if you like it.

GitHub Dynamic Animated Quote Generator

GitHub logo shravan20 / github-readme-quotes

Dynamic quote generator for your GitHub readmes

github-readme-quotes

Dynamic quote generator for your GitHub readmes

banner

alt PRs Welcome Open Source? Yes! GitHub contributors Pull Request Counts last commit deployment-status community chat

Github Readme Quotes

Copy and paste the following markdown content to display the quote.

![Quote](https://github-readme-quotes.herokuapp.com/quote)
Enter fullscreen mode Exit fullscreen mode

Themes

You can display your quote in different themes without any manual customization.

Use ?theme=THEME_NAME parameter as shown below.

![Quote](https://github-readme-quotes.herokuapp.com/quote?theme=dark)
Enter fullscreen mode Exit fullscreen mode

Available Themes

dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, dracula

Gotham

Quote

Dark

Quote

Light Theme

Quote

You can explore different themes here.

Feel free to contribute different themes.

Layouts

You can also change the layout of your templates.

Use ?layout=LAYOUT parameter as shown below

![Quote](https://github-readme-quotes.herokuapp.com/quote?theme=dark&layout=socrates)
Enter fullscreen mode Exit fullscreen mode

Layout 1 (Default)

Quote

Layout 2 (Socrates)

Quote

You can explore different layouts here.

Feel free to contribute different layouts.

Animations

You can also add animations to your templates.

Use ?animation=ANIMATION paramater as shown below

![Quote](https://github-readme-quotes.herokuapp.com/quote?theme=dark&animation=grow_out_in)
Enter fullscreen mode Exit fullscreen mode

Animation 1

Quote

You can explore different animations…

Collapse
ileriayo profile image
Ileriayo Adebiyi

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!

Collapse
odalet profile image
odalet

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

Collapse
koraylinux profile image
Koray Biçer

I think the simplest profile page is mine.

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

Collapse
shadowscientist profile image
Shadow Scientist

Simple yet cool! ❤️

Collapse
vindiv profile image
Vincenzo Di Vico

After reading this article i've created my readme. it's a work in progress and i'll update it, but i'm happy of the result. i've used an animation of me in my real office in flat style and with this avatar. next time i'll "upgrade" the animation with more element

Collapse
jamesgeorge007 profile image
James George

I've built a GitHub Action that updates README with the recent activity of a user.

GitHub logo jamesgeorge007 / github-activity-readme

Updates README with the recent GitHub activity of a user

GitHub Activity in Readme

Updates README.md with the recent GitHub activity of a user.

profile-repo


Instructions

  • Add the comment <!--START_SECTION:activity--> (entry point) within README.md. You can find an example here.

  • It's the time to create a workflow file.

.github/workflows/update-readme.yml

name: Update README
on
  schedule
    - cron: '*/30 * * * *'
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    name: Update this repo's README with recent activity

    steps:
      - uses: actions/checkout@v2
      - uses: jamesgeorge007/github-activity-readme@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The above job runs every half an hour, you can change it as you wish based on the cron syntax.

Please note that only those public events that belong to the following list show up:-

  • IssueEvent
  • IssueCommentEvent
  • PullRequestEvent

You can find an example here.

Custom commit message

Specify a custom commit message with the COMMIT_MSG

Collapse
rodrigograca31 profile image
Rodrigo Graça 👨🏻‍💻🐛

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

Collapse
aayushidroid profile image
Aayushi Sharma

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

aayushi-droid






Collapse
rdnine profile image
Rafael Duarte

What a nice feature!

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

Thanks 👍

Collapse
jmau111 profile image
Julien Maury

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






Collapse
king11 profile image
Lakshya Singh

I made mine after seeing this post thanks a lot.

My Readme : Profile

Collapse
kkvanonymous profile image
Kunal Kumar Verma

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

Collapse
danmba profile image
Dan

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.

Collapse
sanchitbajaj02 profile image
Sanchit Bajaj

Profile Image
My Github Profile.
If you like my work, do give a ⭐

Collapse
ketanrajpal profile image
Ketan Rajpal

Ketan Rajpal Github Profile Readme

My Github Profile Readme

Collapse
mridul037 profile image
Collapse
zeecnla profile image
Cesar Melchor

Thanks for this! I had no idea 🤯. I have to think about how creative to make mine!

Collapse
anitajoseph profile image
Anita Joseph

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

Collapse
caffiendkitten profile image
DaNeil C

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