Monica Powell

Posted on Jul 11, 2020 • Updated on Jul 13, 2020 • Originally published at aboutmonica.com

How To Create A GitHub Profile README

#github #branding #markdown

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.

Create a new repository with the same name (including casing) as your GitHub username: https://github.com/new
Create a README.md file inside the new repo with content (text, GIFs, images, emojis, etc.)
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)
Push changes to GitHub (if you made changes locally i.e., on your computer and not github.com)

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.

Jason Lengstorf

@jlengstorf

hey, check out the new @github profile README! this is a really nice addition — I love that we can add some context (and/or nonsense) to our GitHub profiles now 😍

see mine: github.com/jlengstorf

thanks to @cassidoo for the heads up that this went live!

00:45 AM - 09 Jul 2020

66 578

donavon "#BLM" west

@donavon

@waterproofheart It's not as creative as @sudo_overflow's readme, but here's what I came up with. I also plan on adding some text below the image with links to my resume, etc.

14:20 PM - 09 Jul 2020

1 2

Pouya

@saadeghi

Is this how we suppose use github's readme?

06:23 AM - 09 Jul 2020

11 182

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

Brian Douglas

@bdougieyo

Check it out. I made MySpace but on @github.

github.com/bdougie - My list is power by a GitHub Action workflow 😏

21:19 PM - 10 Jul 2020

56 564

Simon Willison

@simonw

Made myself a self-updating GitHub personal README! It uses a GitHub Action to update itself with my latest GitHub releases, blog entries and TILs github.com/simonw

03:49 AM - 10 Jul 2020

88 689

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

Nate Moore

@n_moore

I embedded a @Spotify Now Playing widget in my @github profile README!

It's an SVG rendered on the fly via @vercel serverless function, included in the README via <img> tag.

Supremely over-engineered, but I discovered lots of fun hacks in the process.

github.com/natemoo-re/nat…

14:50 PM - 12 Jul 2020

110 763

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

Yuan Tang

@terrytangyuan

I just created my @github profile README as well with a bunch of badges. This is really a brilliant idea. We may no longer need to maintain our personal website. We can write blogs as issues, manage Wiki and task board, free traffic analytics and CI/CD. github.com/terrytangyuan

14:05 PM - 10 Jul 2020

4 42

kathy ☁️

@pifafu

hey, so we heard ya & are trying out a thing where you CAN have a readme on your @github profile...
@mikekavouras built it btw! re: twitter.com/pifafu/status/…

22:33 PM - 27 May 2020

kathy ☁️ @pifafu
👋 hiii—if you use @github, i was wondering: what are some of the things you would want others on GitHub to know about you?

1134 6314

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.

Latest comments (45)

Sanchit Bajaj • Dec 25 '20 • Edited

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

Ketan Rajpal • Dec 9 '20

My Github Profile Readme

Vincenzo Di Vico • Dec 8 '20

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

Shravan Kumar B • Nov 22 '20

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

GitHub Dynamic Animated Quote Generator

shravan20 / github-readme-quotes

Dynamic quote generator for your GitHub readmes

github-readme-quotes

Dynamic quote generator for your GitHub readmes

Github Readme Quotes

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

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

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)

Available Themes

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

Gotham

Dark

Light Theme

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)

Layout 1 (Default)

Layout 2 (Socrates)

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)

Animation 1

You can explore different animations…

View on GitHub

Vadorequest • Sep 3 '20 • Edited

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!

James George • Aug 17 '20

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

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.

Instructions

Add the comment  (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.

Override defaults

Use the following input params to customize it for…

View on GitHub

Puneet Gopinath • May 21 '21

Hey James George, you no longer maintain it. So here is a fork of it to use instead:

Readme-Workflows / recent-activity

Add your recent activity to your profile readme!

Recent Activity

This GitHub Action is a Fork of the original GitHub Activity Readme Action by jamesgeorge007.
Its our goal is to improve the original GitHub Action while also providing new features for the users.

Live Preview

This is an example live preview that is updated every time a commit is pushed using github actions.

Last Updated: Thursday, May 20th, 2021, 3:17:39 PM (GMT)

❗️ Closed issue #5 in Readme-Workflows/recent-activity
🎉 Merged PR #6 in Readme-Workflows/recent-activity
🗣 Commented on #3 in Readme-Workflows/recent-activity
❗️ Closed issue #4 in Readme-Workflows/recent-activity
💪 Opened PR #6 in Readme-Workflows/recent-activity

Settings

The Action currently has the following Settings that you can set through the with option.

Option	Description	Default
`GH_USERNAME`	The User to get latest activity from	Repository Owner
`COMMIT_MSG`	The Commit Message to use when updating the README	`⚡ Update README with the recent activity`
`MAX_LINES`	How many activities to display	`5`

…

View on GitHub

Harshal Jadhav • Aug 4 '20 • Edited

Here's mine which shows your latest medium blogs.

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

mridul037 • Aug 1 '20 • Edited

check my out github.com/mridul037/mridul037

Ankit Kumar • Jul 23 '20

Gave it a shot.

Ankit512 / Ankit512

This is the personal profile readme for...well me!

Hi there, I'm Ankit 👋👨‍💻

Hi, I'm Ankit Kumar, final year CSE undergrad from SRM Institute of Science and Technology, KTR 🏫. I'm also an indie game developer 🎮 snekaing my way into Data Science and Analytics 🤫.

Beside's developing stuff, I enjoy watching and playing sports ⚽, listening to music 🎧 and eating food 🍕. Apart from that, I'm also a pundit when it comes to sports like Football, Basketball and F1 🧐.

I'm also a die-hard supporter of Manchester United Football Club ⚽❤.

Uncomfortable thought: Warm Soda 😣.