I've seen a lot of people generate a clean HTML page with ChatGPT or Claude, feel great about it for about 30 seconds, and then completely freeze when it comes time to actually put it online.
GitHub Pages is one of the best answers to that problem — free, permanent URLs, HTTPS included, zero server config. But the setup has a few quiet gotchas that trip people up the first time. This guide covers the actual steps, plus the two things the official docs gloss over.
What GitHub Pages is (and isn't)
GitHub Pages turns a repository into a website. That's it.
You push your files to a branch, flip a setting, and GitHub builds and serves the site from that branch. It's designed for static content — HTML, CSS, JavaScript, images. If your project needs a backend, a database, or server-side rendering, GitHub Pages isn't the right tool. But for portfolios, landing pages, documentation, demos, and microsites, it's hard to beat.
A few things worth knowing upfront:
- It's free for public repos, and also available on private repos with a GitHub account
- It supports custom domains — you're not stuck with
username.github.io
- It doesn't support server-side code (PHP, Node, Python, etc.)
- For frameworks like Next.js or Vite that require a build step, you'll need GitHub Actions — this guide focuses on plain HTML/CSS/JS projects
Prerequisites
Before you start, make sure you have:
- A GitHub account
- A repository with your site files
- An
index.htmlat the root (this becomes your homepage)
If you haven't pushed your project yet, create a new repo on GitHub, then either upload files directly via the UI or push from your terminal:
git init
git add .
git commit -m "initial commit"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main
Step 1: Open Repository Settings
Go to your repository on GitHub and click the Settings tab at the top.
Step 2: Find the Pages Section
In the left sidebar, scroll down to Pages under the "Code and automation" section.
Step 3: Configure the Source
Under Build and deployment, you'll see a "Source" dropdown. Select Deploy from a branch.
Then choose:
Branch: usuallymainormaster
Folder:/root(unless you've put your files in a/docssubfolder)
Click Save.
Step 4: Wait for the Build
GitHub will start building your site. This usually takes 30 seconds to 2 minutes the first time.
Refresh the Settings → Pages page. When it's done, you'll see a green banner:
"Your site is live at
https://username.github.io/repo-name/"
Step 5: Open Your Site
Your site lives at:
https://yourusername.github.io/your-repo-name/
Bookmark it. From now on, every time you push changes to the selected branch, GitHub Pages will redeploy automatically — usually within a minute or two.
The two things that catch people off guard
1. The URL path matters
If your repo is named portfolio and your GitHub username is alice, your site is at alice.github.io/portfolio/ — not alice.github.io/. That trailing /portfolio/ affects how relative paths in your HTML work. If you link to ./style.css, it works. If you hardcode /style.css, it breaks (because that resolves to the root domain, not your project subfolder).
The fix: use relative paths for all assets, or set a <base> tag in your <head>:
<base href="/your-repo-name/">
2. Changes don't always show up immediately
GitHub Pages has CDN caching. After a push, you might see the old version for a minute or two even after the build finishes. Hard-refresh (Ctrl+Shift+R / Cmd+Shift+R) usually clears it. If you're seeing stale content during active development, consider working with a local server (npx serve . or VS Code's Live Server extension) and only pushing when you want to check the live URL.
Updating your site
Every push to the configured branch triggers a new deploy. Your workflow from this point on is just:
git add .
git commit -m "update content"
git push
No FTP, no control panel, no manual uploads.
Deploying AI-generated HTML to GitHub Pages
If you used ChatGPT, Claude, or Gemini to generate the HTML, the process above still applies — you'd copy the code, save it as index.html, commit, push, and configure Pages.
There's also a Chrome extension called HTML Deployer that skips those steps. It detects HTML code blocks directly inside the AI chat, shows a preview, and lets you publish to GitHub Pages (or Netlify, or FTP) from the same tab without touching a terminal. Useful if you're iterating quickly on a page and don't want to context-switch between tools.
Either approach gets you to a live URL. The manual route teaches you more about how GitHub Pages works; the extension is faster for repetitive deploys.
What to try next
Once you're comfortable with the basic setup, a few things worth exploring:
Custom domain: Add aCNAMEfile to your repo root and configure your DNS — the GitHub Pages docs cover this well
GitHub Actions for build steps: If you move to a framework that compiles output (like Astro or Eleventy), Actions lets you run the build before deploying
Jekyll: GitHub Pages has native Jekyll support, which can turn markdown files into a blog with minimal config
GitHub Pages is one of those tools that scales from a 5-minute static page all the way to a proper documentation site or blog. Starting with plain HTML is the right move — you can always layer on complexity later.