Skip to content
Back to blog

How to Make a GitHub Profile README That Stands Out

How to create a GitHub profile README in the repository named after your username, what to include, how to pin your best repos and keep the page tidy.

7 min read

What a profile README is

A GitHub profile README is a Markdown file that appears at the top of your public profile page, above your repositories. GitHub shows it when someone visits your account. It is a short introduction you control, and it can point people to the projects you want them to see.

Most visitors arrive from somewhere else: a talk, a repository you published, a comment you left on an issue. They look at your profile to decide whether you are worth following. A clear profile that explains what you build helps them decide quickly. For the rest of the repository side of your work, see how to get GitHub stars for your project.

Create the special repository

The profile README lives in a public repository whose name is exactly your GitHub username. If your username is example-dev, the repository must be called example-dev, and it must be public for the README to show on your profile. GitHub's own documentation on profile READMEs walks through the steps and any changes to the process, so check the GitHub Docs if the menus look different.

  1. Click the plus icon at the top right of GitHub and choose New repository.
  2. Type your username exactly as it appears in your profile URL.
  3. Add a short description, such as My GitHub profile, so you recognise it later.
  4. Make the repository public and tick the option to add a README file.
  5. Edit the README file and save it. Your profile updates after the save.

If the README does not appear, check the repository name for typos and confirm that the repository is public. Changes can take a short while to show, so refresh the profile page before you assume something is wrong.

What to put at the top

Start with a short introduction in your own words. Two or three sentences should cover what you work on, what you care about and what kind of collaboration you are open to. Avoid job-title slogans. A line such as I build small command-line tools for working with spreadsheets, mostly in Python is more useful to a visitor than a list of buzzwords.

Next, add a short section that says what you are working on now. Keep it honest and easy to update. A paragraph about a current project tells people the profile is active. A profile that still promotes a project you abandoned years ago does the opposite.

Add a way to get in touch, such as a link to your website or a contact address you are comfortable publishing. Do not include private details you would not want public.

Pin the repositories that matter

Pinned repositories sit near the top of your profile, under your README. GitHub limits how many you can pin, and the current limit is listed in its documentation. Use the slots for the work you most want people to see, not for the newest repositories by default.

Choose pins that answer a visitor's question. A pinned project that solves a clear problem, has a good README and shows recent activity is ideal. A pinned tutorial repository or an example that teaches a concept also works well if it is polished. Remove a pin when the project is no longer maintained, and replace it with something current.

In your profile README, you can describe the pinned projects in a sentence each and link to the repositories. Describing them in text helps people who scan the README without clicking through, and it gives search engines something to read.

Describe your work in text, not decoration

Some profile READMEs are full of animated banners, counters and automatically generated charts. A few of these can be pleasant, but many slow the page down, break on phones and add little for a visitor who wants to know what you build. Write a plain section with your main projects, skills and interests, and add one simple image if it earns its place.

A short list of projects, each with a sentence on the problem it solves, is more useful than a wall of technology logos. If you do list skills, group them by what you use them for, such as building for the web or writing automated tests, rather than listing every tool you have ever opened.

Keep images small and give them descriptive alt text. Text is searchable and works for everyone, including people using screen readers or slow connections.

Badges and stats, used sparingly

A badge or two on your profile can show something real, such as a project's build status or a licence. The guide to GitHub README badges explains which badges help and which just add noise. If you want to create one for a project, the GitHub badge generator writes the markdown for you.

Stats cards that count your contributions can be interesting, but treat them as decoration. They do not show the quality of your work, and a visitor who sees a low number in a quiet month may read more into it than you intended. Place them below your main content, not above it.

Keep the profile tidy

A profile README is not a one-time job. Revisit it when you finish a project, change focus or start to use a new tool. A monthly glance is enough for most people. When you check, look for three things: links that now lead to a 404 page, descriptions that no longer match the code and pins that no longer reflect your best work.

Keep the length in check as well. A profile a visitor can scan on a phone without much scrolling is usually the right size. If you have a long history to share, put it on your website or in a separate post and link to it.

Mistakes that make a profile look abandoned

  • The profile is blank, with only the default repositories and no introduction.
  • The README was written years ago and mentions technologies or roles that no longer apply.
  • Pinned repositories are all forks, empty projects or tests you never intended to share.
  • Links point to websites that no longer exist.
  • Every section is generated and none is written by you, so nothing sounds like a person.
  • The page is so long that the important part is hidden below a screen of images.

The fix for most of these is a short editing session. Read the profile as a stranger would, then remove what they would not miss.

A simple template to start from

If you are stuck, use this order and fill in your own details:

  1. A two- or three-sentence introduction in your own words.
  2. What you are working on at the moment.
  3. Two to four projects you are proudest of, each with one sentence on what it does and a link.
  4. How to reach you or where to read more.
  5. One small, optional image or badge, with alt text.

Once that works, add pins to match the projects you list, and check that every link resolves.

Connect the profile to your projects

Your profile is the hub. Each project it links to needs its own clear README, and a good README is the difference between a visitor who follows the link and one who leaves. The pillar guide on getting GitHub stars covers the whole path, and the GitHub services overview lists the options if you want a hand with reach.

People who follow you are often looking for updates, so a profile that points to recent releases works well. The GitHub followers page describes the follower service in more detail, and the stars and forks pages cover the project side. None of these replaces a profile that tells the truth about what you do and keeps up with it.

Frequently asked questions

Nobody outside GitHub can promise a ranking effect, so do not plan around one. The practical benefit is that visitors get a clear answer about who you are and what you build, which is worth more than any ranking trick.

Can I use a private repository for my profile README?

The profile README has to be in a public repository to appear on your public profile. If you want to keep some details private, leave them out of the public file rather than trying to hide them in a private repository.

How often should I change my profile README?

Update the current-work section whenever your focus changes, and review the whole file every few months. Frequent small changes are normal, and they show the profile is maintained.

Should I include my employer?

That is your choice. Many people leave it out or keep it general, especially if they work on projects outside their job. Only include what you are comfortable making public.

Share this article

Written by

Editorial Team

Official updates and guides from our team.

More articles

Keep reading

Over 3,800,000 delivered so far

Start Growing Today

Organic promotion for followers, likes, and views. Join the creators who are already winning.

24/7 Live Support 30-Day Guarantee Secure Payments Gradual Delivery
Get started