DEV Community

Cover image for How to Deploy a Static Website to GitHub Pages (The Basics + What No One Tells You)
Backrun
Backrun

Posted on

How to Deploy a Static Website to GitHub Pages (The Basics + What No One Tells You)

#github #html #webdev #beginners

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.html at 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
Enter fullscreen mode Exit fullscreen mode

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: usually main or master
  • Folder: /root (unless you've put your files in a /docs subfolder)

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/
Enter fullscreen mode Exit fullscreen mode

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/">
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 a CNAME file 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.

Source: https://backrun.co/blog/how-to-deploy-github-pages

Top comments (0)