How to make a GitHub profile README
A profile README is a README.md in a public repository named exactly like your username. GitHub shows it at the top of your profile, above your pinned repositories. Here is how to make one, and what to put in it.
See your profile in a template
Steps
- Create the repository. On GitHub, create a new repository with exactly your username as its name (for example
octocat/octocat). GitHub tells you it is a special repository. - Make it public and add a README. Keep it public and tick "Add a README file" so
README.mdexists from the start. - Write the content. Edit
README.mdwith the sections below, in Markdown. GitHub also accepts some HTML, such as<img>,<p align="center">and<details>. - Add visuals. Paste a stats card or start from a template instead of a blank file.
- Commit and check. Commit the file and open
github.com/your-username. The README appears at the top.
What to put in it
- One line about what you do. "Backend engineer building developer tools in Go" beats "Welcome to my profile".
- What you're working on now. One or two current projects or roles, with links.
- Two or three projects with proof. A link, one sentence on what it does, and why it matters (users, stars, what you learned).
- Your stack. A short list of the languages and tools you actually use, not every one you've touched.
- How to reach you. Website, email or the one social profile you check.
Mistakes to avoid
- Too long. Visitors skim. If it needs scrolling on a laptop, fold sections away with
<details>. - A wall of badges. Fifty logos say less than three good projects, and each badge is one more image that can break.
- Out-of-date details. An old job title or a dead project link is worse than none. Generated cards help because they update themselves.
- Things GitHub strips. Scripts, iframes and custom CSS don't work in a README; animation has to come from images such as SVG or GIF.
The faster way
Type your username in the GitHub profile README generator to see your profile built in a finished template, then copy the Markdown or publish it from GitSkins. To compare tools first, read the best GitHub profile README generators.
Build yours now
Questions
Why isn't my profile README showing?
The repository must be public, named exactly like your username (same spelling), and have README.md in its root on the default branch.
Can I use HTML in a GitHub README?
Some. GitHub allows tags like img, p with align, details and summary, but strips scripts, iframes and custom CSS.
How long should a profile README be?
Short enough to skim: a one-line introduction, a few projects and contact links. Fold anything longer into sections that open on click.