GitHub Profile README: How to Create a Stunning Profile Page
Step-by-step setup, a copy-paste template, badges, and stats cards
What Is a GitHub Profile README?
A GitHub profile README is a Markdown file that shows up at the top of your GitHub profile page, above your pinned repositories. It is your personal landing page on GitHub: a place to introduce yourself, show your tech stack, and link to your best work.
The trick is simple. Create a public repository with the same name as your username, add a README.md file, and GitHub displays it on your profile. That repository is often called the “special repository”.
github.com/octocat
Hi, I’m Octo
Full-stack developer. I build tools for people who love plain text.
↓ Pinned repositories appear below your README
octocat/octocat <-- repository name = username
└── README.md <-- shown on github.com/octocatWhen the repository is set up correctly, GitHub shows a small banner in the repo saying that the README is visible on your public profile.
Step-by-Step Setup
The whole process takes about two minutes.
1. Create a repository named exactly like your username
Go to github.com/new. In the Repository name field, type your GitHub username exactly. If your username is octocat, the repository must be octocat. GitHub will show a hint that you have found a special repository.
2. Make it public and add a README
Set the visibility to Public and check Add a README file. GitHub creates a starter README.md for you.
3. Edit README.md
Open the file and click the pencil icon (or press . to open the web editor). Replace the starter content with your own Markdown. You can also clone the repo and edit it locally in any editor.
4. Commit your changes
Click Commit changes. Visit github.com/your-username and your README appears at the top of your profile. Every future commit to this file updates your profile instantly.
git clone https://github.com/your-username/your-username.git
cd your-username
# edit README.md
git add README.md
git commit -m "Update profile README"
git pushBasic Template
Start with this clean template and replace the details with your own. It covers the essentials: a greeting, an about section, your tech stack, what you are working on, and how to reach you.
Hi there, I’m Alex 👋
Full-stack developer who loves clean code and good coffee.
- 🔭 I’m currently working on Project Atlas, an open-source task manager
- 🌱 I’m learning Rust and WebAssembly
- 💬 Ask me about TypeScript, React, and Node.js
- ⚡ Fun fact: I debug better after a long walk
TypeScript · React · Node.js · PostgreSQL · Docker
- Website: alex.dev
- LinkedIn: linkedin.com/in/alex
- Email: hello@alex.dev
<h1 align="center">Hi there, I'm Alex 👋</h1>
<p align="center">Full-stack developer who loves clean code and good coffee.</p>
## 👨💻 About Me
- 🔭 I'm currently working on **Project Atlas**, an open-source task manager
- 🌱 I'm learning **Rust** and **WebAssembly**
- 💬 Ask me about **TypeScript**, **React**, and **Node.js**
- ⚡ Fun fact: I debug better after a long walk
## 🛠 Tech Stack
TypeScript · React · Node.js · PostgreSQL · Docker
## 📫 How to Reach Me
- Website: [alex.dev](https://alex.dev)
- LinkedIn: [linkedin.com/in/alex](https://linkedin.com/in/alex)
- Email: hello@alex.devThe centered heading uses HTML (align="center"), which GitHub supports. Everything else is plain Markdown, so it also renders in any Markdown viewer.
Adding Badges
Badges are small colored labels that show your tech stack or link to your social profiles. Most are generated by shields.io, a free service that returns an image from a URL. The preview below is a simplified imitation; on GitHub, the real badges also include logos.
Python TypeScript React Docker LinkedIn
The URL pattern is https://img.shields.io/badge/LABEL-HEXCOLOR?style=STYLE&logo=LOGO&logoColor=COLOR. Change style to flat, flat-square, for-the-badge, or plastic.
Clickable social badges
Wrap a badge in a link to turn it into a button:
[](https://linkedin.com/in/your-name)For a deeper look at the syntax, see our guide on Markdown badges.
Stats Cards
Many profiles show live statistics: total stars, commits, top languages, and contribution streaks. These are generated by third-party services that render an image from a URL. Replace your-username with your GitHub username.
Note: These cards are provided by independent third-party projects, not by GitHub. They can be slow, rate-limited, or go offline, and the URLs and options may change. Check each project’s documentation before relying on them.
GitHub stats card
From the github-readme-stats project. Shows stars, commits, pull requests, and issues.
Top languages card
Also from github-readme-stats. Shows the languages you use most across your public repositories.
Streak stats
From the github-readme-streak-stats project. Shows your current and longest contribution streaks.
Put cards side by side with a small HTML snippet:
<p align="center">
<img height="150" src="https://github-readme-stats.vercel.app/api?username=your-username&show_icons=true" />
<img height="150" src="https://github-readme-stats.vercel.app/api/top-langs/?username=your-username&layout=compact" />
</p>Sections to Include
You do not need every section. Pick the ones that tell your story and skip the rest.
| Section | What goes in it |
|---|---|
| About Me | A two- to four-line introduction: who you are, what you do, and what you care about. |
| Tech Stack | Languages, frameworks, and tools you use, shown as a list or a row of badges. |
| Current Projects | What you are building or learning right now, with links to the repositories. |
| Blog Posts | Links to your latest articles. Can be updated automatically with a GitHub Action. |
| GitHub Stats | Optional stats and top-languages cards (third-party services). |
| Connect With Me | Website, LinkedIn, X, email, or anything else people should use to reach you. |
| Fun Facts | One or two personal details that make you memorable: hobbies, a favorite editor, a hot take. |
Tips for a Great Profile
- Keep it concise. Visitors skim. Aim for something that fits on one or two screens.
- Update it regularly. Change “currently working on” when the project changes. A stale README is worse than a short one.
- Show personality. One honest, specific detail beats a list of buzzwords.
- Link to real work. Point to your best two or three repositories, articles, or demos, and pin the same repos below your README.
- Use emoji sparingly. One emoji per heading is fine; an emoji on every line is hard to read.
- Preview before you commit. Open the file in a Markdown viewer to check how headings, lists, and tables look.
Common Mistakes
Wrong repository name
The repository name must match your username exactly. If the README does not appear on your profile, check spelling, hyphens, and capitalization first. Do not add suffixes like -profile or -readme.
| Username | Repository | Result |
|---|---|---|
octocat | octocat | Works |
octocat | octocat-readme | Not shown |
octocat | octocat-profile | Not shown |
Private repository
The repository must be public. A private repo will not display its README on your profile. You can change visibility under Settings → General → Danger Zone.
Overly long README
A profile is not a résumé. Long walls of text, huge animated banners, and a dozen stats cards slow the page and bury the useful parts. Keep only what helps a visitor decide to follow you, hire you, or open a repo.
Broken image links
Third-party badge and stats services can change or disappear. Test your page in a private window, and avoid images that depend on a service you do not trust to stay up. Always add alt text so the profile still reads well if an image fails.
FAQ
How do I create a GitHub profile README?
Create a new public repository named exactly like your GitHub username, check “Add a README file”, then edit README.md and commit. The content appears at the top of your profile at github.com/your-username.
What is the special repository for GitHub profile README?
It is a public repository whose name matches your username (for example, octocat/octocat). GitHub treats the README.md at its root as your profile README and shows it above your pinned repositories.
Can I use HTML in my GitHub profile README?
Yes. GitHub renders a safe subset of HTML inside Markdown, including <div align="center">, <img>, <picture>, <details>, <a>, and tables. Scripts, iframes, and custom CSS are stripped for security.
Preview Your Markdown with MDViewer
Drafting your profile README? MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — headings, lists, tables, code blocks, and more. Lite is free; Pro adds editing, Git history, and PDF export.
Requires macOS 13.0 or later. Intel and Apple Silicon.