How to Create a GitHub Profile README
A GitHub profile README is the pinned Markdown page that appears at the top of your GitHub profile. This guide walks through creating one from scratch, using GPRG to skip the manual Markdown work.
1. Create the special profile repository
On GitHub, create a new public repository named exactly the same as your username (e.g. if your username is alex, the repo must be named alex). GitHub detects this repo name automatically and treats its README.md as your profile README.
2. Fill in your info
Open the GPRG generator and connect your GitHub username. Add your bio, location, and current role - GPRG pulls in what it can automatically and lets you fill the rest.
3. Write your bio with AI
Pick a tone - Professional, Witty, Casual, or Minimal - and let GPRG's AI bio generator draft your intro in seconds. Edit it to match your voice before moving on.
4. Select your tech stack
Search and select from 200+ tech icons covering languages, frameworks, and tools. Keep this list to what you actually use - a long badge wall reads as clutter, not credibility.
5. Choose a design and add stats
Pick a template layout, then enable dynamic stats: contribution streaks, top languages, and repo stats. Preview how it will look on both desktop and the GitHub mobile app.
6. Export and publish
Copy the generated Markdown or download the README.md file, commit it to your profile repository, and refresh your GitHub profile page to confirm it's live.
Common mistakes to avoid
- Repository name doesn't exactly match your GitHub username (case and spelling matter).
- Repository is set to private - profile READMEs only render from public repos.
- README.md isn't at the root of the repository.
- Too many badges/images stacked at the top, pushing your bio below the fold.
- Stats card image URLs that aren't publicly reachable, causing broken images or a stuck "0".
Guide FAQs
How do I make my GitHub profile show a README?
Create a public repository with the exact same name as your GitHub username, add a README.md file to it, and GitHub automatically displays that README at the top of your profile page.
Why isn't my GitHub profile README showing up after I created it?
The most common causes are: the repository name doesn't exactly match your username, the repository is private instead of public, or the file isn't named README.md at the repository root.
Does my GitHub profile README repository need to be public?
Yes - GitHub only displays profile READMEs that live in a public repository.
Can I edit my GitHub profile README after publishing it?
Yes - edit README.md in your profile repository and commit the change; your profile page updates automatically.
What's the difference between a profile README and a regular repo README?
A profile README appears on your personal GitHub profile page and lives in a repo named exactly like your username, while a regular repo README only documents that specific project.
How do I add GitHub stats and streak badges to my README?
Use GPRM's stats card tool to generate an image or Markdown snippet for your stats, then paste it into your README - make sure the image URL stays publicly accessible so GitHub can render it.
Can I use GPRM without a GitHub account?
You can build and preview a README without signing in, but you'll need a GitHub account to actually publish it to your profile repository.
What are the most common mistakes when creating a profile README?
The most frequent issues are an incorrect repo name, a private repository, broken badge URLs, and overloading the top of the README with too many badges or images.