GitHub profile README ideas
A good GitHub profile README says who you are in one line, what you are building now, and where to see your best work, then gives one clear way to reach you. Visuals help when they show real work: a GitHub city badge from Caldera links visitors to every repo you build, sized by recent commits.
Updated 2026-10-18 · by mjonesone, LLC
A simple structure
- One line: what you build and for whom.
- Now: two or three things you are working on this month.
- Best work: links to the repos or products you want judged by.
- A visual: your activity as an image that opens somewhere useful.
- Contact: one channel you actually check.
Add your GitHub city
[](https://caldera.social/gh/you)The card shows public repos and commits this year and opens your city. See GitHub README badge.
Keep it current without effort
A README goes stale when it depends on you remembering to edit it. Link to something that updates itself: a Caldera page rebuilds from GitHub every 6 hours, and with Obsidian it also carries a daily journal written from your notes.
Avoid
- Walls of badges with no meaning.
- Lists of every technology you have touched.
- Stats with no link to the work behind them.
Questions
How do I create a profile README?
Create a public repo with the same name as your username and add a README.md; GitHub shows it on your profile.
What should I put first?
One line on what you build, then what you are working on now.
Are visual stats worth it?
Yes, when they link to the work. A city badge opens every repo you build.
Is the Caldera badge free?
Yes.