Profile README Generator

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

  1. 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.
  2. Make it public and add a README. Keep it public and tick "Add a README file" so README.md exists from the start.
  3. Write the content. Edit README.md with the sections below, in Markdown. GitHub also accepts some HTML, such as <img>, <p align="center"> and <details>.
  4. Add visuals. Paste a stats card or start from a template instead of a blank file.
  5. Commit and check. Commit the file and open github.com/your-username. The README appears at the top.

What to put in it

Mistakes to avoid

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.