Blog
3 min read

How to Create a GitHub Profile README

Step-by-step guide to creating a GitHub profile README. Set up the special repository, write compelling content, and add dynamic elements.

GitHub profile READMEs appear at the top of your profile page. They're a powerful way to introduce yourself, showcase your work, and stand out to recruiters and collaborators. Here's how to create one.

Setting up the special repository

GitHub displays a profile README when you create a repository that matches your username. If your username is janedoe, create a repository called janedoe.

  1. Go to github.com/new
  2. Set the repository name to your exact GitHub username
  3. Make it public
  4. Check "Add a README file"
  5. Click "Create repository"

GitHub will show a hint: "janedoe/janedoe is a special repository." That confirms you're on the right track.

What to include

Introduction

Start with who you are and what you do. Keep it to 2-3 sentences. Avoid generic statements — be specific about your interests and expertise.

markdown
# Hi, I'm Jane 👋

Full-stack developer building tools for the open-source community.
Currently working on developer productivity at Acme Corp.

Current work

Tell visitors what you're focused on right now:

markdown
## What I'm up to

- 🔭 Building a CLI tool for database migrations
- 🌱 Learning Rust and WebAssembly
- 💬 Ask me about TypeScript, React, or system design

Tech stack

List your primary technologies. Badges work well here:

markdown
## Tech Stack

![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)
![React](https://img.shields.io/badge/-React-61DAFB?style=flat&logo=react&logoColor=black)
![Node.js](https://img.shields.io/badge/-Node.js-339933?style=flat&logo=node.js&logoColor=white)

Featured projects

Highlight 3-4 of your best repositories:

markdown
## Featured Projects

- **[project-name](https://github.com/janedoe/project-name)** — Short description of what it does
- **[another-project](https://github.com/janedoe/another-project)** — What makes this one interesting

GitHub stats

GitHub Readme Stats generates dynamic cards showing your activity:

markdown
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=janedoe&show_icons=true&theme=radical)

Other popular widgets:

  • Top Languages: github-readme-stats.vercel.app/api/top-langs/?username=janedoe
  • Streak Stats: github-readme-streak-stats.herokuapp.com/?user=janedoe
  • Activity Graph: Shows your contribution pattern over time

Contact links

Make it easy for people to reach you:

markdown
## Connect

[![LinkedIn](https://img.shields.io/badge/-LinkedIn-0A66C2?style=flat&logo=linkedin)](https://linkedin.com/in/janedoe)
[![Twitter](https://img.shields.io/badge/-Twitter-1DA1F2?style=flat&logo=twitter&logoColor=white)](https://twitter.com/janedoe)
[![Portfolio](https://img.shields.io/badge/-Portfolio-000?style=flat&logo=vercel)](https://janedoe.dev)

Dynamic content

GitHub Actions for auto-updating

You can use GitHub Actions to keep your profile README fresh. Popular automations:

  • Latest blog posts — Pull your RSS feed and list recent articles
  • Recent activity — Show your latest commits, PRs, and issues
  • Spotify — Display what you're currently listening to
  • WakaTime — Show weekly coding stats by language

Example workflow

yaml
name: Update README
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update blog posts
        uses: gautamkrishnar/blog-post-workflow@v1
        with:
          feed_list: "https://janedoe.dev/rss.xml"

Design tips

  1. Keep it scannable. Use headings, badges, and short paragraphs. Nobody reads walls of text.
  2. Show, don't tell. Link to projects instead of listing skills without context.
  3. Update regularly. A stale profile README is worse than none.
  4. Match your brand. Choose a consistent color scheme for badges and stats widgets.
  5. Test on mobile. Many people browse GitHub on phones — check your layout.

Common mistakes

  • Too long. Profile READMEs should be 1-2 screen heights. Beyond that, people stop reading.
  • Too many badges. Pick 8-10 key technologies, not every tool you've ever used.
  • Broken images. Always test your README after pushing. Use absolute URLs for images.
  • No call to action. Tell people what to do next — check out a project, read a blog post, reach out.

Portfolio READMEs for repositories

If you're also looking to improve your project READMEs, we have a portfolio README guide and can generate READMEs automatically from your codebase. Check your existing README quality with our free README scorer.

For badge ideas and configuration, see our GitHub README badges guide.