Publishing with GitHub Pages

A repository on GitHub becomes a website in a few clicks. That’s GitHub Pages. No server to rent, no files to transfer.

The setup

We’ll use the repository you pushed in the previous lesson.

1. Open your repository on GitHub
2. Click Settings in the top menu
3. Choose Pages in the left menu
4. Under Source, choose “Deploy from a branch”
5. Under Branch, choose main and the folder / (root), then Save

That’s it. Wait a moment, reload, and your public URL appears near the top.

https://username.github.io/repository-name/

Open it, see your page, and you’re published. Anyone in the world can now reach it.

Updating means pushing

Once published, editing locally and pushing updates the live site automatically.

git add .
git commit -m "Rewrite the profile text"
git push

No file transfer step — that’s the big win of publishing through Git. The loop becomes: change it, record it, and it goes live.

Three reasons a page comes up blank or 404

Check these in order.

1. index.html isn’t at the top level

GitHub Pages serves the index.html at the top level of your repository as the home page.

my-site/
├── index.html   ← it needs to be here
├── style.css
└── images/

Tuck it away in src/index.html and there’s no home page to find, so you get a 404.

2. Capitalization doesn’t match

This is the most common cause. Windows and macOS treat filenames case-insensitively, so Style.css works on your machine. GitHub Pages’ server is strict about it, and that’s where things fall apart.

<!-- Works locally, fails once published -->
<link rel="stylesheet" href="Style.css">
<img src="images/Shima.PNG">

Keeping all filenames lowercase is the safe habit.

3. Your paths are absolute

A path starting with / means “from the very top of the site.” Since GitHub Pages URLs include the repository name, that shifts everything out of place.

<!-- Breaks -->
<link rel="stylesheet" href="/style.css">

<!-- Safe -->
<link rel="stylesheet" href="style.css">

Check what you’re publishing

In a public repository, everything is visible to everyone — not just your HTML, but any notes or test images sitting in the folder. Before publishing, take one look through the repository on GitHub’s page view.

How it compares to the alternatives

If you’ve learned Git, GitHub Pages is the least work.

Summary of this lesson

1. Settings → Pages → set the branch to main and save. That’s the whole setup
2. Updating is just git push — no transfer step
3. When nothing shows, check where index.html is, filename capitalization, and your paths