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.
| Condition | The usual slip |
| The repository name equals your username | A different letter case, or a repository named like your site, username.github.io, which is a different thing |
| The repository is public | It was created private and never switched |
| A file called README.md sits in the root | The file is in a folder, or has another extension |
| The file has content | An 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.
| Keep | Skip |
| One-sentence intro and a "currently" line | A logo for every tool you have touched |
| Three or four projects in a table with two or three columns, which stays readable on a phone | Paragraphs describing each project, since the pinned repositories already do that |
| A single line of contact links where you actually answer | Quotes, jokes and trophy walls above the intro |
| Long lists inside a collapsed section | Games 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.
| Element | Depends on | Our call |
| Badges for stack, license, stars | shields.io | Keep a handful that are true. Our badge generator writes the Markdown. |
| Stats and top-language cards | A shared card server, or files you host yourself | Use 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 GIFs | Your own repository | Upload them to the same repository and keep the file size small. |
| Visitor counter | A counter service | Your 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.