What a profile README actually is
A profile README is a short document that GitHub shows at the top of your profile page.
It is one of the few places where you control the first thing a visitor reads, before they see your repositories or contribution activity.
That makes it a useful tool, but it is not free of trade-offs, and it only works if a few technical conditions are met.
This guide covers what a profile README can do, GitHub's exact requirements for showing one, and what can make it disappear.
It also helps you decide whether adding one fits your situation.
Per GitHub's documentation, a profile README is a customizable section at the top of your profile page.
You decide what to include, giving you full control over how you present yourself.
GitHub's profile documentation lists it alongside your bio, contribution activity, pinned items, status, and achievements.
Because it is written in Markdown, you can format text and include emoji, images, and GIFs using GitHub Flavored Markdown.
GitHub suggests content visitors may find useful, such as an about-me section describing your work and interests.
It also recommends highlighting contributions you are proud of, with context about them.
In practice, that means the README is not a resume duplicate.
It is a short orientation for a visitor: who you are, what you work on, and where they should look next.
The requirements: when GitHub shows your README
GitHub displays your profile README only if all of the following are true, per GitHub's profile README documentation:
- You have created a repository with a name that matches your GitHub username.
- The repository is public.
- The repository contains a file named README.md in its root.
- The README.md file contains any content.
One documented exception matters for troubleshooting.
If you created a public repository matching your username before July 2020, GitHub will not automatically show its README on your profile.