A GitHub profile README is a special repository named exactly like your GitHub account. Whatever you put in its README.md shows at the top of your profile page. To make one: create a public repository with your username as its name, add a README.md, and write in it. This is the same procedure GitHub documents.
I saw an article about this feature some time ago and thought it was a good place to show what I do. Maybe it would also bring a bit of traffic to my side projects.
I don’t like writing about myself. I can’t do it well (yes, I know, I run a blog). But GitHub gives you a basic template, so you only edit a few entries and you have something close to mine.
How to create a GitHub profile README
- Go to https://github.com/new and create a repository as you normally would. Name it exactly like your account (mine is
kodziak). GitHub then shows a message saying this is a special repository. - Tick the option to initialize it with a
README.md. That file appears on your profile automatically. - Edit the file, commit, and make sure the repository is public.
I recommend starting with private while you work on it, so nobody sees a half-finished page. Switch to public when you’re happy. One catch from the GitHub docs: if you created a repository with your username before July 2020, GitHub won’t show its README on your profile until you select Public in the repository settings.
GitHub profile README template
Copy this skeleton and replace the placeholders. Everything in it is plain Markdown, so it renders anywhere GitHub does.
## Hi, I'm <your name>
<One or two sentences: what you do and what you are working on now.>
## What I work on
- [<Project name>](<link>): <one line about what it does>
- [<Project name>](<link>): <one line about what it does>
## Writing
- [<Blog post title>](<link>)
- [<Blog post title>](<link>)
## Get in touch
- Website: [<yourdomain>](<link>)
- LinkedIn: [<handle>](<link>)
- Email: <[email protected]>
Add a section for a talk, podcast or open source project if you have one. Delete any section you can’t fill with something real.
What to put in a GitHub profile README
- Who you are. Name, role and what you are working on. One short paragraph.
- Your best work. Two or three pinned-style links with one line each. Recruiters and collaborators look here first.
- Where you write or talk. A blog, a podcast, a newsletter.
- How to reach you. Email or a social link. At the end of mine I wrote that I answer every message, and I do.
Dynamic widgets (stats cards, recent-activity feeds) are optional. Some of the examples below use them. They need a GitHub Action or a third-party service, so they add maintenance. Static text never breaks.
How I structured my profile README
I looked at a few profiles I liked (better than mine, honestly) and split my page into sections. In 2020 I also had a podcast, so I wanted that visible next to the blog:
- Who am I?
- What I do (blog, podcast)
At the bottom I put my social media links.
Rules I followed
I like emojis, so every section header had one. It adds a bit of color to a text-only page.
Everything else is plain. No heavy images, no gifs, no banners with jumping ducks. Someone landing on my profile should get the main information in a few seconds.
Keep it short. Nobody reads long walls of text on a profile (this article is already pushing it).
GitHub profile README examples
Profiles worth opening, from simple to busy:
- kodziak/kodziak: mine. Short intro, the companies I run, contact links.
- WaylonWalker/WaylonWalker: a banner, social icons and a feed of latest posts.
- stephenajulu/stephenajulu: a written bio with a list of projects.
- abhisheknaiidu/abhisheknaiidu: auto-updating widgets for weekly activity.
For many more, browse the community list awesome-github-profile-readme.
Summary
Keep your profile README fun, simple and short. But do make one.
If you set up yours after reading this, send me the link and I’ll add it to the list above. And if you want a hand with test automation rather than profile pages, see how I work with teams.