Skip to content

GitHub profile README: make it show, keep it short, keep it fresh

A GitHub profile README is a repository named exactly like your username with a README.md in it. It works when the first ten lines say who you are and what you are building, and everything else is optional.

By
GitWow editorial team
Updated
updated
Reading
6 min read

01GitHub shows the README only when four conditions hold, and a wrong letter case breaks one of them.

02Five or six sections in the top ten lines beat a catalogue of twenty-five.

03Every card or counter loads from someone else's server, so add only the ones that report a fact.

04Let GitHub Actions refresh what changes, and delete what you will not maintain.

We have spent more than ten years growing accounts on social networks, with over 10 billion reach and close to a billion followers across the accounts we run. The lesson carries over to GitHub: a stranger gives a profile a few seconds, so the page has to answer "who is this" before the first scroll.

A profile README is a ten-line landing page

The README sits above your pinned repositories and is the one part of the profile where you control the layout. Two template guides we read agree on the viewing habit. One says most visitors give it five seconds. The other says the top 10 lines are what a laptop shows before scrolling. Plain version: write the first screen as if it were the only screen.

That gives the page one job per visitor type. A recruiter wants your stack and your best work. A maintainer who found your pull request wants to know what you do. A developer who might follow you wants a reason. Pick one reader for the top ten lines and let the lower part serve the others.

GitHub itself calls the profile README more flexible than the bio, so use the bio for the short line and the README for the proof. Our profile README generator builds a first version from a short form if you want a draft to edit. For the profile around it, the pins, photo and what a hiring manager sees, read how to make a good GitHub profile.

Make it show: GitHub checks four things, and letter case counts

According to GitHub Docs, the README appears only if all of these are true. Most "my README is not showing" threads break one of them.

ConditionThe usual slip
The repository name equals your usernameA different letter case, or a repository named like your site, username.github.io, which is a different thing
The repository is publicIt was created private and never switched
A file called README.md sits in the rootThe file is in a folder, or has another extension
The file has contentAn empty file created by a tick box and never edited

One more case is documented. If the repository was created before July 2020, the README does not appear on its own and you press the Share to profile button in the repository. A README also disappears if the file is deleted, the repository goes private or the name stops matching your username, which happens after a rename.

After you commit, run the public profile through our profile analyzer. One of its twelve checks looks for a repository named like your username, so a missing README shows up as a failed row with a fix.

Start with one honest sentence about what you do now

The intro decides whether the rest gets read. Replace "Hi there" with one sentence on what you work on and what you are open to. Three lines are enough: who you are, what you build, what you want to hear about.

I build payment APIs in Go. Right now I am writing a rate limiter and learning Rust. Ask me about testing HTTP clients.

That sample is invented, but the shape is what to copy: a role, a current project, an invitation. The bio field is the same job in 160 characters, and our bio generator drafts five of them from a role and a stack. Write the bio first and reuse its wording in line one, so the sidebar and the README agree.

Keep five or six sections and cut the rest

Idea lists run from 25 to 50 sections. One guide tells you to pick five or six of 25, another picks eight to twelve of 50. Both agree on the direction. Our rule for the top ten lines is shorter than either: one intro, one current project, a small project table, one line of links.

KeepSkip
One-sentence intro and a "currently" lineA logo for every tool you have touched
Three or four projects in a table with two or three columns, which stays readable on a phoneParagraphs describing each project, since the pinned repositories already do that
A single line of contact links where you actually answerQuotes, jokes and trophy walls above the intro
Long lists inside a collapsed sectionGames and guestbooks, unless a playful profile is what you want

GitHub documents the collapsed section and the table syntax, and both save space. The profile sidebar already holds up to four social links, so repeat a link in the README only when it sends people somewhere the sidebar does not. For finished layouts to compare, browse our profile README examples.

Badges, cards and counters earn a place only when they report a fact

Each of these is an image fetched from a third-party domain when someone opens your profile. If that server is slow, the visitor sees a broken picture or the alt text. Decide what you accept before you paste.

ElementDepends onOur call
Badges for stack, license, starsshields.ioKeep a handful that are true. Our badge generator writes the Markdown.
Stats and top-language cardsA shared card server, or files you host yourselfUse files you commit. Our README stats generator draws SVG cards in the browser to put beside the README, so nothing is fetched at view time. The popular card service offers more than 30 themes if you accept the dependency.
Banners and GIFsYour own repositoryUpload them to the same repository and keep the file size small.
Visitor counterA counter serviceYour choice, see below.

The counter is where sources split. GitHub's own list of standout profiles includes a hit counter, while one audit of 45 hiring managers found that 78% read a visitor counter as a vanity widget. GitHub itself shows no profile view statistics, so a counter is the only number you can get. If you want one, our profile views counter generator builds the line. If your reader is a recruiter, leave it out.

For a dark and a light theme, the GitHub quickstart shows a responsive image with the picture element. Use it for banners, since a transparent PNG that looks fine on white disappears on dark.

Let Actions refresh what changes and delete what you will not maintain

A "currently" line that is a year old tells a visitor you stopped looking. Three things update on their own through a GitHub Actions workflow in your profile repository: a list of your latest blog posts from an RSS feed, weekly coding stats from WakaTime, and a snake animation drawn from your contribution graph. The workflows are community projects such as blog-post-workflow, snk and waka-readme.

The trade is a workflow to keep alive. If a section changes less than once a quarter, write it by hand with a date. If it changes weekly and you will not touch it, automate it or remove it.

Make it readable for everyone with five checks from GitHub

The GitHub Blog has a post of five tips for an accessible profile README. They cost nothing and also help search and skimming.

  • Write descriptive link text, and avoid several links with the same label.
  • Add alt text to images. The post suggests treating it like a tweet: succinct, concise and descriptive.
  • Use real headings in order, not bold text standing in for a heading.
  • Write plain language.
  • Use proper list markup. Emoji used as bullets make a screen reader read the list as one paragraph.

The post also asks for care with emoji: a screen reader speaks each one by name, so a row of five is tiring to hear. One more limit worth knowing: GitHub truncates README content beyond 500 KiB, which a profile should never approach.

Pin the work first, then let other developers find it

The README tells a visitor who you are, and the pinned repositories prove it. Pin three to five projects, give each a one-line description, then ask for attention where it counts. On GitWow, developers follow and star each other's public profiles and repositories by hand from their own accounts, and the only thing you share is a public link. Show your profile to real developers, and get free stars for the pinned project you are proudest of.

Frequently asked questions

How do I create a GitHub profile README?

Create a new public repository named exactly like your username, tick Add a README file, write your content and commit. GitHub then shows the file above your pinned repositories. Our profile README generator produces the first draft.

Why is my profile README not showing?

Check the four conditions in order: the repository name matches your username letter for letter, the repository is public, README.md is in the root and the file has content. A repository created before July 2020 also needs the Share to profile button. Also confirm that you opened the profile, not the page of a repository called username.github.io.

What should I put in my GitHub profile README?

One sentence on what you do now, a "currently" line, a table of three or four projects and one line of contact links. Keep them in the first ten lines. The examples in our README gallery show layouts that follow the same shape.

How do I add GitHub stats to my profile README?

Draw two SVG cards with our README stats generator, commit the files next to your README and paste the two image lines it gives you. The alternative is a shared card service, which saves the commit but loads from another server every time someone opens your profile.

How do I keep my profile README updated automatically?

Add a GitHub Actions workflow to your profile repository. Community workflows can list your latest blog posts, add weekly WakaTime stats or draw a snake from your contribution graph. Each one runs on a schedule and commits the change for you.

Can I make a profile README for my organization?

Yes, through a special repository named .github instead of username/username. The README for the organization profile lives inside it, and a dev.to guide from GitHub's own account walks through the steps.

Do GitHub profile visitor counters help?

They give you a rough number, since GitHub shows no profile view statistics. They can also cost you with a hiring reader: one audit of 45 hiring managers found 78% see a counter as a vanity widget. Add one if your audience is other developers, and skip it if your audience is a recruiter.

Read next

GitWow is a free community for growing your GitHub repositories and profile with help from other members.

Start free

47k members ยท 900+ actions a day