# all·markdown

GitHub profile README template

Make your profile-README.md

Fill these in and the whole file updates. Nothing 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.
-->

Visual

Open in the editor Runs in this tab, nothing is uploaded.

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:

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 sanitizer’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.

Organizations

Create a repository called .github in the organization and put the file at profile/README.md. It renders on the organization’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 organization have one too?
Yes. Create a repository called `.github` in the organization and put `profile/README.md` in it. That renders on the organization's page, and the mechanism is otherwise the same.

Sources