Profile & Portfolio

01 The Profile README

A README is just a text file that GitHub automatically displays on a repo's page — short for "read me," it's meant to explain what a project is before anyone digs into the code. GitHub also has a special trick: if you create a repository with the exact same name as your username and add a README.md to it, GitHub renders that one specific README at the very top of your profile page — above your pinned repos, visible to anyone who visits github.com/your-username.

It's the only repo on GitHub that behaves this way, and it's the closest thing GitHub has to a personal "about me" page.

02 Creating It

• Click + → New repository.
• Name it exactly your GitHub username — GitHub will actually notice and show a message like "username/username is a special repository" once you type it correctly.
• Make it Public (private profile READMEs don't render on your profile).
• Tick Add a README file, then click Create repository.
• Click the pencil icon on the README to edit it directly in the browser, or clone it and edit locally like any other repo.

03 What to Include

Keep it scannable — most visitors skim for ten seconds. A solid structure:

• A one- or two-line intro — who you are and what you work on.
• Currently working on / learning — shows you're active, not just a static bio.
• Tech stack — languages and tools you actually use, not every technology you've ever heard of.
• Featured projects — one-line description and a link, for anything not already obvious from your pinned repos.
• How to reach you — email, LinkedIn, portfolio site, whatever you actually check.

README files are written in Markdown — a simple way to format text using plain symbols instead of a toolbar: ## before a line makes it a heading, **text** makes it bold, and [label](url) turns it into a clickable link. GitHub reads these symbols and renders styled text automatically, in any README. Here's a minimal starting template using exactly those three tricks:

04 Stats & Badges

You can drop in small auto-generated images that pull live data straight from your account — no code or hosting required on your end. Two popular ones people embed as plain Markdown image links:

• GitHub stats card (via the community github-readme-stats project) — shows your star count, commits, and top languages as an image.
• Shields.io badges — small pill-shaped labels for things like your latest release, license, or follower count.

These are just image URLs, so you paste them into your README like any other image:

05 Pinning Repositories

By default your profile shows your most recently active repos — not necessarily your best ones. Pin the ones you actually want people to see:

• Go to your profile → Customize your pins.
• Choose up to six repositories (your own, or ones you've contributed to).
• Pick projects with a clear README, a real description, and — ideally — a live demo link or screenshot, over half-finished experiments.

06 The Contribution Graph

That grid of green squares on your profile counts commits, issues, and PRs on public repos (and on private repos too, if you opt in). A few things that trip people up:

• Commits only count if the email in your commit (git config user.email) matches an email verified on your GitHub account.
• To include private-repo activity in the graph, go to your profile → Contribution settings → enable "Include private contributions on my profile." The exact commit content stays hidden — only the square lights up.

Don't chase the graph for its own sake — a slightly quieter graph with real, working projects beats one padded with meaningless commits.

07 General Polish

• Give every repo a real README — what it does, how to run it, a screenshot if it's visual. This matters far more than badges.
• Add a description and topics to each repo (the gear icon next to "About" on a repo's page) — topics make your projects searchable on GitHub.
• Pick a license if you want others to be able to reuse your code — GitHub can add one for you when creating or editing a repo.
• Delete or archive dead experiments rather than leaving twenty half-finished repos visible — quality over quantity.
• Keep it updated. A profile that mentions "currently learning React" three years ago reads worse than no profile README at all.