How to Create a GitHub Profile README

How to create a GitHub profile README in five steps

GitHub displays a profile README when three conditions are true: the repository name exactly matches the account username, the repository is public, and a README.md file with content is stored at its root. The README then appears near the top of the public profile. Managed user accounts cannot use the feature.

• Sign in to GitHub and create a new repository.
• Enter your username exactly as the repository name, including capitalization.
• Set the repository visibility to Public.
• Select the option to initialize the repository with a README, or add README.md at the root afterward.
• Edit the file, preview the Markdown, and commit the change.

Start with a restrained profile README

A profile README is an introduction, not a second résumé and not a dashboard of every tool you have tried. Lead with what you do, the kind of work you care about, and two or three places a visitor should go next. A recruiter, collaborator, or customer should be able to understand the page before scrolling.

Use GitHub Flavored Markdown for headings, links, images, task lists, tables, details blocks, and code when those formats make information easier to scan. Keep the first version short enough to maintain.

# Hi, I'm Sam

I build accessible web applications and maintain small open-source tools.

## Current work
- Improving Example Project
- Writing about frontend performance

## Find me
- [Portfolio](https://example.com)
- [LinkedIn](https://www.linkedin.com/in/example)

What belongs on the profile

Useful material includes a one-sentence role or specialty, current focus, selected repositories, a portfolio or personal site, and a contact route you intentionally publish. If you are available for work, say what kind and where. If the profile supports an open-source project, explain the contribution path and link to the repository's own documentation.

Let pinned repositories carry detailed project evidence. The profile README should explain why those projects matter and help a visitor choose where to look. Avoid duplicate lists that go stale in two places.

What to leave out

Do not publish private email addresses, phone numbers, client details, credentials, internal project names, travel plans, or anything that answers a security question. Repository history is public too, so removing a secret in a later commit does not safely erase the earlier exposure.

Use badges, activity cards, animations, and large images sparingly. Third-party images reveal a visitor's request to the image host and can disappear when that service changes. A wall of badges also makes the important links harder to find.

Make images and links accessible

Give meaningful images useful alternative text. Decorative images should not repeat the nearby heading. Avoid text embedded inside an image when normal Markdown can present the same information. Check contrast inside screenshots and diagrams because GitHub's light and dark themes can change the surrounding context.

Use link text that explains the destination instead of repeating 'click here.' Preview the README on a narrow screen, confirm that tables do not hide important content, and keep animated media from becoming the only way to understand the page.

Troubleshoot a README that does not appear

First compare the repository name with the current username character for character. Then confirm that the repository is public and that README.md is at the top level rather than inside another folder. Open the file and make sure it contains committed content on the repository's default branch.

If the username changed, the special repository name must match the new username. If the account is managed by an organization as a managed user account, GitHub does not support a profile README for that account type.

Maintain it like a small homepage

Review the profile every few months and after a job, focus, username, or primary project changes. Remove dead links, finished 'current' work, and badges that no longer say anything useful. The best GitHub profile README stays accurate because it is small enough to update.