How to Set Up Your GitHub Profile README — Complete Step-by-Step Guide

The GitHub profile README lives in a special repository. The trick is that the repository name must be exactly the same as your GitHub username. When GitHub detects a public repository with your username as the name and a README.md inside it, it automatically displays that README on your profile page.

To create it:

• Go to github.com and make sure you're logged in
• Click the + icon in the top right corner → New repository
• In the "Repository name" field, type your exact GitHub username — for example if your username is alexchen99, the repository name must be alexchen99
• Set it to Public — a private repository will not work for profile READMEs
• Check the box that says "Add a README file"
• Leave everything else at defaults
• Click Create repository

Now that the repository exists, you need to put content into the README.md file. You have two options here — write it yourself in markdown, or use a tool to generate it.

Option A — Use the ReadmeDesign Generator (Recommended)

Go to readmedesign.com/readme-generator, fill in your details — name, role, tech stack, social links, which widgets to include — and click "Copy Markdown." The generator produces a complete, formatted README in about 2 minutes. You then paste it into your README.md file.

Option B — Write it yourself

If you prefer to write from scratch, here is a minimal starting template that covers the sections most people want:

How to preview before committing

If you want to see exactly how your markdown will render on GitHub before saving it, paste it into the ReadmeDesign Sandbox. It renders markdown exactly as GitHub does, including badges and HTML elements.

You have two ways to get your content into the README.md file — directly on GitHub in the browser, or via Git on your local machine. If you're setting this up for the first time, the browser method is easier.

Method A — Edit directly on GitHub (easiest)

• Go to your new repository at github.com/YOUR_USERNAME/YOUR_USERNAME
• Click on the README.md file
• Click the pencil icon (Edit this file) in the top right of the file view
• Select all the existing content and delete it
• Paste your new README content
• Scroll down to the "Commit changes" section
• Leave the commit message as is or write something like "Add profile README"
• Make sure "Commit directly to the main branch" is selected
• Click Commit changes

Method B — Via Git on your local machine

If you prefer working locally:

After the push, visit your GitHub profile in a browser — the README will be live immediately.

The stats cards — the ones that show your commit count, streak, and top languages — are images generated by a third-party service called github-readme-stats. They're not built into GitHub. You add them as markdown image links pointing to the stats API.

There are three settings you should always enable that most people miss:

Replace YOUR_USERNAME with your actual GitHub username in all three URLs. The widgets will start showing your real data immediately after you commit this to your README.

A static README is fine. But a README that updates itself — showing your latest blog posts, your actual coding hours this week, your most recent GitHub activity — feels alive rather than abandoned. GitHub Actions lets you automate this with scheduled workflows that run in the background for free.

This step is optional but worth doing if you write blog posts anywhere or use Wakatime.

Before anything else — enable write permissions

Workflows that update your README need permission to write to your repository. By default they can only read.

• Go to your username repository on GitHub
• Click Settings → Actions → General
• Scroll to "Workflow permissions"
• Select "Read and write permissions"
• Click Save

Auto-update with your latest blog posts

If you write on Dev.to, Hashnode, Medium, or any platform with an RSS feed, this workflow pulls your five most recent posts and lists them in your README every day automatically.

First add these two comment markers to your README exactly where you want the posts to appear:

Then create a new file at exactly this path inside your username repository: .github/workflows/blog-posts.yml

Save the file, commit it, and the workflow will run at 8am UTC every day going forward. To test it immediately: go to the Actions tab in your repository → click the workflow name → click Run workflow.

This is a setting most developers miss. If you do professional work in private repositories, your public contribution graph looks nearly empty even though you've been coding every day. GitHub has a setting to show private contribution activity without revealing what you were working on.

• Go to github.com/YOUR_USERNAME (your profile page)
• Scroll down to your contribution graph
• Click the small "Contribution settings" dropdown in the top right of the graph
• Check "Private contributions"

Your contribution graph will immediately update to include private repo activity. The graph shows that you contributed but doesn't reveal which repositories or what the commits contained.