Quick Deploy Guide: GitHub Pages

Why GitHub Pages:

• Free (no credit card needed)

• Easy (a few clicks + one command)

• No server needed (GitHub hosts it for you)

• Custom domain support (if you want your own URL later)

• Perfect for static sites (HTML/CSS/JS projects)

Step-by-Step Deploy

Prerequisites: You need a free GitHub account. If you don’t have one, go to github.com → Sign Up (takes 2 minutes).

---

Part 1: Prepare Your Project Locally

In your project folder (where your files are), initialize Git:

# Initialize Git tracking
git init

# Stage all your files
git add .

# Save a snapshot
git commit -m "Initial commit: my awesome project"

What you’ll see: Git confirms the commit with something like:

[main (root-commit) abc1234] Initial commit: my awesome project
 3 files changed, 42 insertions(+)
 create mode 100644 index.html
 create mode 100644 script.js
 create mode 100644 styles.css

---

Part 2: Create a Repository on GitHub (The Website Part)

Step 1: Open your browser and go to github.com/new

(Or: Click the + icon in the top-right corner of GitHub → “New repository”)

Step 2: Fill out the form:

Repository name: my-timer-app (must match your project folder name - or pick any name you want)

Description: (optional) “A simple timer with start/stop/reset buttons”

Public or Private?

• Public = Anyone can see it (required for free GitHub Pages)

• Private = Only you can see it (GitHub Pages costs money for private repos)

IMPORTANT: Do NOT check these boxes:

• ❌ “Add a README file”

• ❌ “Add .gitignore”

• ❌ “Choose a license”

(You already have files - these options are for starting from scratch)

Step 3: Click the green “Create repository” button

---

Part 3: Connect Your Local Project to GitHub

You’ll see a page with instructions. Look for the section that says:

…or push an existing repository from the command line

Copy the commands shown (they’ll have YOUR username). They look like:

git remote add origin https://github.com/YOUR-USERNAME/my-timer-app.git
git branch -M main
git push -u origin main

Paste them into Terminal (in your project folder) and press Enter.

What you’ll see: Git uploads your files:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.2 KiB | 1.2 MiB/s, done.
Total 5 (delta 0), reused 0 (delta 0)
To https://github.com/YOUR-USERNAME/my-timer-app.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

What this did: Your local files are now on GitHub! Refresh the GitHub page in your browser - you should see your files listed.

---

Part 4: Enable GitHub Pages (Make It Live!)

Step 1: On your repo page, click “Settings” (top-right area, last tab in the menu)

Step 2: In the left sidebar, scroll down and click “Pages” (under “Code and automation”)

Step 3: Under “Build and deployment”:

Source: Select “Deploy from a branch” (should be default)

Branch:

• Click the dropdown (says “None”)

• Select “main”

• Leave the folder dropdown as ”/ (root)”

Step 4: Click “Save”

You’ll see: A blue/green box appears:

✓ Your site is live at https://YOUR-USERNAME.github.io/my-timer-app/

(Takes 30-60 seconds to build. Refresh the page if you don’t see it yet)

---

Part 5: Visit Your Live Site!

Click the link (or type it in your browser):

https://YOUR-USERNAME.github.io/my-timer-app/

🎉 Your app is now on the internet! Anyone with the link can use it.

---

Making Updates Later

After you change your code:

# In your project folder
git add .
git commit -m "Made buttons bigger"
git push

GitHub Pages auto-updates (takes 1-2 minutes). Refresh your live site to see changes.

---

Troubleshooting

“404 - There isn’t a GitHub Pages site here”

• Wait 2-3 minutes (first deployment is slow)

• Check Settings → Pages → make sure branch is “main”

• Make sure repo is Public (Settings → Danger Zone → Change visibility)

Page shows folder listing instead of website

• Make sure your main HTML file is named index.html (exactly, lowercase)

• If it’s named something else, rename it to index.html

Site doesn’t update after pushing changes

• Check if push succeeded: git status should say “nothing to commit, working tree clean”

• Wait 2-3 minutes for GitHub Pages to rebuild

• Hard refresh in browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)

For React/Vite projects:

# Add to vite.config.js:
base: '/projectname/'

# Build:
npm run build

# Deploy dist/ folder
# (Use gh-pages package or manual)

---