Home › GitHub Profile Setup Guide
Setup Guide

GitHub Profile README Setup Guide

Learn how to use any GitHub Profile README template in just a few minutes.

Step 1: Create Your GitHub Profile Repository

GitHub only displays a profile README when the repository name matches your GitHub username.

Example

GitHub Username YOUR_USERNAME
Repository Name YOUR_USERNAME
For example:
Username: johndoe
Repository: johndoe/johndoe

⚠️ If the repository name does not exactly match your username, GitHub will not display the README on your profile.

Step 2: Make the Repository Public

When creating the repository:

  • ✅ Set the repository visibility to Public
  • ✅ Add a README.md file

Your repository should look like:

YOUR_USERNAME/
├── README.md

Step 3: Choose a Template

Browse the available templates on our website. When you find one you like:

  • Click Copy
  • Open your README.md
  • Paste the template
  • Commit the changes

Refresh your GitHub profile to see the new design.

Step 4: Replace Placeholder Information

Most templates contain placeholder values. Update them with your own information:

Your Name
Job Title
GitHub Username
Portfolio
Email
LinkedIn
X (Twitter)
Projects
Skills
Technologies

Search for placeholders like:

YOUR_NAME
YOUR_USERNAME
YOUR_EMAIL
YOUR_PORTFOLIO

Step 5: Upload Images (If Required)

Some templates include banners, GIFs, or profile images. If the template contains:

<img src="./banner.gif" width="100%" />

Upload the image to the same repository as your README.md.

YOUR_USERNAME/
├── README.md
├── banner.gif
├── profile.png
└── assets/

Step 6: Use an Assets Folder (Recommended)

For better organization, keep images inside an assets folder.

YOUR_USERNAME/
├── README.md
└── assets/
    ├── banner.gif
    ├── profile.png
    └── coding.gif

Then reference them like this:

<img src="./assets/banner.gif" width="100%" />

Step 7: Using GitHub Image URLs

If you prefer using image URLs instead of local files:

https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_USERNAME/main/assets/banner.gif

Replace:

  • YOUR_USERNAME
  • Image filename
  • Branch name (if different from main)

Step 8: Update GitHub Widgets

Many templates use GitHub widgets like:

  • GitHub Stats
  • Streak Stats
  • Profile Views
  • Contribution Graph

Replace every occurrence of YOUR_USERNAME with your GitHub username.

Step 9: Commit Your Changes

After editing the README:

  • Commit the changes.
  • Wait a few seconds.
  • Refresh your GitHub profile.

Your profile README should now be visible.

Troubleshooting

My README isn't showing

  • ✔ Repository name must exactly match your GitHub username.
  • ✔ Repository must be Public.
  • ✔ README.md must be in the repository root.
  • ✔ Changes must be committed to the default branch.

Images aren't loading

  • Check that the filename is correct.
  • Check that the image is uploaded.
  • Check that the image path is correct.
<img src="./assets/banner.gif">