How do I make a GitHub profile README appear?

Create a public repository named exactly after your username — github.com/you/you — with a README.md in it. GitHub renders that file at the top of your profile. When the names match, the repository creation page offers to set it up and tells you it is a special repository.

Why is mine not showing?

Three usual causes: the repository is private, the name does not match your username exactly including case, or the file is not called README.md at the repository root. All three fail silently — the repository simply looks ordinary.

Should I add stats cards and streak widgets?

They are third-party images fetched on every profile view, so they break when the service behind them is rate-limited or goes away, and they say little that your pinned repositories do not. If you want them, pick one rather than four.

Can I use HTML in it?

Yes, the same subset GitHub allows in any README — align attributes for centring, img with a width, details for collapsible sections. Script and style tags are stripped, and so are style attributes.

Does an organisation have one too?

Yes. Create a repository called `.github` in the organisation and put `profile/README.md` in it. That renders on the organisation's page, and the mechanism is otherwise the same.

GitHub profile README template

Fill it in and copy it Open in the editor Opens as profile-README.md, ready to edit. Nothing is uploaded.

The shape of it — edit here, or open the full template

Markdown

Result

Runs entirely in this tab. Open the full editor to work on a real document.

Fill it in and take it

The whole file is below. Type into the boxes to replace the placeholders, then copy it or save it — nothing here is sent anywhere, and there is nothing to sign up for.

<!--
  Your GitHub profile README.

  It lives in a repository named exactly after your username — github.com/<you>/<you>
  — in a file called README.md. GitHub then renders it at the top of your
  profile page. Create that repository and it offers to set this up for you.

  Keep it to roughly one screen. A profile README is a business card, not a CV.
-->

# Hi, I'm Your Name

One sentence on what you build and who it is for.

## What I'm working on

- **[project-name](https://github.com/you/project-name)** — one line on what it does
- **[other-project](https://github.com/you/other-project)** — and this one

## What I know well

`TypeScript` `Go` `Postgres` `Kubernetes`

<!-- A short list of things you would be happy to be asked about beats a wall
     of every technology you have opened. -->

## Elsewhere

- [Website](https://example.com)
- [Blog](https://example.com/blog)
- [Mastodon](https://example.social/@you)

<!--
  Two things worth knowing before adding more:

  Stats cards and streak widgets are third-party images. They pull from an
  external service on every profile view, they break when that service is
  rate-limited, and they say very little that your pinned repositories do not.

  Pinned repositories are set on the profile itself rather than in this file,
  and they are usually the most useful thing on the page.
-->

A profile README is an ordinary README.md in a repository named exactly after your username. GitHub renders it at the top of your profile page.

github.com/your-username/your-username  →  README.md

The repository must be public and the name must match your username exactly. Get it right and GitHub tells you on the creation page that this is a special repository; get it wrong and you have made an ordinary repository with no error message.

Treat it as a business card

One screen. The pinned repositories underneath do the detailed work, and they are configured on the profile itself rather than in this file — a README that lists every project duplicates them badly.

What earns its place:

Who you are, in a sentence. What you build, and who for.
Two or three current things, each with a link and a line.
What you would be happy to be asked about. A short list beats every technology you have ever opened.
Where else to find you.

What to leave out

Stats cards and streak widgets. They are images fetched from a third-party service on every view of your profile. When that service is rate-limited — and the popular ones frequently are — visitors get a broken image where your contribution count should be. They also say very little that pinned repositories do not.

A full CV. If that is the goal, a resume that exports to PDF serves it better than a profile page.

Animations and marquees. They are HTML in a sanitiser’s path, and mostly what survives is the reason people leave.

HTML

The same subset as any README: align for centring, <img width> for sizing, <details> for a collapsible block. <script>, <style> and style attributes are all stripped. See GitHub Markdown for the full list.

Organisations

Create a repository called .github in the organisation and put the file at profile/README.md. It renders on the organisation’s page the same way.

Common questions

How do I make a GitHub profile README appear?: Create a public repository named exactly after your username — github.com/you/you — with a README.md in it. GitHub renders that file at the top of your profile. When the names match, the repository creation page offers to set it up and tells you it is a special repository.
Why is mine not showing?: Three usual causes: the repository is private, the name does not match your username exactly including case, or the file is not called README.md at the repository root. All three fail silently — the repository simply looks ordinary.
Should I add stats cards and streak widgets?: They are third-party images fetched on every profile view, so they break when the service behind them is rate-limited or goes away, and they say little that your pinned repositories do not. If you want them, pick one rather than four.
How long should it be?: One screen. It is a business card — the pinned repositories underneath do the detailed work, and they are configured on the profile rather than in this file.
Can I use HTML in it?: Yes, the same subset GitHub allows in any README — align attributes for centring, img with a width, details for collapsible sections. Script and style tags are stripped, and so are style attributes.
Does an organisation have one too?: Yes. Create a repository called `.github` in the organisation and put `profile/README.md` in it. That renders on the organisation's page, and the mechanism is otherwise the same.