Home / Guides / GitHub Pages Guide

GitHub Pages Guide

GitHub Pages turns any GitHub repository into a live website. It is free, requires no server setup, and updates automatically when you push changes.

1. Activate GitHub Pages on a Repo

  1. Go to your repository on github.com
  2. Click Settings (top menu bar, near the right)
  3. Click Pages (left sidebar, under "Code and automation")
  4. Under "Source," select Deploy from a branch
  5. Under "Branch," select main and / (root)
  6. Click Save
  7. Wait about 2 minutes. Refresh the page. A URL will appear at the top.

2. Your Personal Site

To create a personal site at username.github.io:

  1. Create a new repository named exactly username.github.io (replace username with your actual GitHub username, all lowercase)
  2. The repo name must match your username exactly. If your username is jsmith25, the repo must be jsmith25.github.io.
  3. Add an index.html file and push it
  4. GitHub Pages activates automatically for this repo. Your site will be live at https://username.github.io

3. Project Sites

Any other repo with Pages enabled becomes a project site.

  • Repo named portfolio becomes https://username.github.io/portfolio
  • Repo named homework-1 becomes https://username.github.io/homework-1

You can have as many project sites as you want. Each one is its own repo.

4. Check if Your Deploy Succeeded

Option A: Go to your repo on GitHub. Look at the most recent commit. A green checkmark means the deploy finished. An orange dot means it is still building.

Option B: Go to Settings > Pages. If the deploy worked, you will see your site URL with a "Visit site" link.

5. Troubleshooting

Page shows your README instead of your site

  • Your homepage must be named index.html (lowercase, exact spelling)
  • GitHub shows README.md by default if no index.html exists

404 error

  • For personal sites: double-check that the repo name matches your username exactly
  • For project sites: make sure Pages is enabled in Settings
  • Wait 2 minutes after your first push. GitHub needs time to build.

CSS or images not loading

  • File paths on GitHub are case-sensitive. Style.css and style.css are different files.
  • Use lowercase for all file and folder names
  • Use relative paths: css/style.css, not /css/style.css or C:\Users\...

Changes not showing up

  • Make sure you pushed your changes (check the commit on github.com)
  • Hard refresh your browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
  • Wait 2 minutes for GitHub to rebuild the site