Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To add an introduction or portfolio to your GitHub profile, create a public repository named exactly after your GitHub username, put a non-empty README.md in its root, then edit and commit the file. GitHub displays it at the top of your profile when those conditions are met. See GitHub’s profile README requirements.
What you need before creating a profile README
- A GitHub account that is not a managed user account. Managed user accounts cannot use profile READMEs.
- A repository whose name matches your GitHub username exactly.
- A public repository with a non-empty file named
README.mdin the repository root.
These requirements apply together. A repository with the right name but set to private, or a README stored in a subfolder, will not meet the documented conditions.
Create the repository and edit its README
- Sign in to GitHub and select New repository.
- Enter your exact GitHub username as the repository name.
- Set the repository visibility to Public and select the option to initialize it with a README.
- Create the repository. Open the README and select Edit README.
- Replace the generated starter text—GitHub’s quickstart notes that it begins with “### Hi there”—with your own content.
- Select Preview to check the rendered page, then commit the changes when you are ready.
GitHub’s profile README guide and writing quickstart describe this setup and editing workflow.
Choose what to include
Use the README to help profile visitors understand who you are and what you do. GitHub offers examples rather than a required template. Useful sections might include:
#1 Best Overall
- A brief introduction and what you work on.
- Professional or personal interests relevant to your work.
- Selected projects or contributions you are proud of.
- Ways to find help or join communities where you participate.
Keep the page focused on information that helps visitors understand your work. For longer project details, link to the relevant documentation rather than turning the profile into a full project manual.
Format and preview the content
Profile READMEs support GitHub Flavored Markdown. You can use headings, lists, links, and other Markdown formatting, and GitHub’s writing guide also demonstrates HTML for images. For an image, include useful alternative text so visitors using assistive technology can understand its purpose.
The guide shows a <picture> element with prefers-color-scheme conditions for serving different images in light and dark modes. It also demonstrates HTML comments, which are hidden in the rendered output. Review the result in Preview before committing, especially when using embedded HTML.
For links or images that point to files in the same repository, GitHub recommends relative paths. GitHub adjusts these paths based on the branch being viewed, and relative links are more dependable when someone clones the repository than links tied to an absolute location. See GitHub’s documentation on repository files.
Publish immediately or review first
If you commit directly to main, GitHub says the changes become visible to profile visitors. To review an update before it appears on your profile, create a branch, make the edits there, and open a pull request; the change is not published to the profile until it is merged.
Check visibility and fix common problems
- The README does not appear: Confirm that the repository name exactly matches your username, the repository is public, and a non-empty
README.mdsits in the root. - The repository is old: If you created the matching public repository before July 2020, open it and select Share to profile if the README is not displayed.
- The README disappeared: GitHub stops displaying it if the README is deleted or emptied, the repository becomes private, or the repository name no longer matches your username.
- Some content is missing in the rendered view: GitHub truncates repository README content beyond 500 KiB.
Once published, the README is part of your public profile: GitHub says details on a public profile are visible to all GitHub users. Consider whether you want particular identity or contact information to be public, especially where local laws, regulations, or cultural norms may affect the risks of sharing it.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Edit an existing profile README
If you already have one, go to your profile page and use the edit control next to the profile README. Make your changes, preview them, and commit directly to main for immediate visibility or use a branch and pull request for review first.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
