GitHub shows a README at the top of your profile only if it is in one special repository. Getting this step right once means every change you make later is one copy and paste away. This lesson sets it up and publishes your README from Profile README Studio.
Create the repository with your exact username
On GitHub, create a new repository:
- Repository name: exactly your username, same spelling. For the user
octocat, the repository isoctocat/octocat - Public: a private repository's README is not shown on your profile
- Leave Add a README file unticked; the studio's Create README.md button adds it in the next step
When the name matches, GitHub shows a note that this is a special repository. That is how you know it is right.
Export your README from the studio
In the studio, click Export. The Put it on your profile section offers:
- Copy markdown: copies the whole README to paste into GitHub's editor
- Download README.md: saves the file, to upload or commit
The export also checks your username on GitHub and links you to the right page: Create the repository if it does not exist yet, then Create README.md, which copies your markdown and opens a new README.md on GitHub to paste it into. If the README already exists, the link opens it for editing instead.
The README comes with its pictures: badges, banners and icons the studio drew. Download all (.zip) gives them as a profile-assets folder; upload it to the repository next to the README (on github.com: Add file, Upload files, and drag the folder in). If your README has cards drawn from your GitHub data (stats, a contribution snake, your latest blog posts), the export also lists the one workflow file that keeps them up to date, with where it goes. The lesson on GitHub Actions covers it.
Put the README at the root
The file must be called README.md and sit at the top of the repository, not in a folder. The simplest way:
- Open your repository on GitHub
- Click the README, then the pencil icon to edit it
- Select everything, paste the markdown from the studio, and commit
Your profile shows the new README a few seconds later.
Know why a README does not show
If your profile shows nothing, it is almost always one of these:
| Problem | Fix |
|---|---|
| The repository name does not match your username exactly | Rename it to your username |
| The repository is private | Make it public in its settings |
The file is not named README.md at the root | Move or rename it |
Update it later
Your layout is saved in your browser, and the address bar always holds a link to it. When you want to change something, open the studio, edit, export, and paste over the old README.
The next lesson goes back into the studio: layouts, and editing right on the page.