If you’ve just finished building your first HTML site and don’t want to pay for web hosting, GitHub Pages is the easiest way to get it online for free. Learning how to host a static HTML website on GitHub Pages takes only a few minutes, requires no server-side language, and gives you a real, working URL you can share with anyone — no credit card, no hosting plan, and no configuration files to fight with.

GitHub Pages is a free static site hosting service built directly into every GitHub repository. It’s designed for exactly the kind of project beginner web designers build first: a simple site made of HTML, CSS, and JavaScript, with no database or backend required. Instead of paying a hosting provider, you simply upload your files to a GitHub repository, flip on a setting, and GitHub publishes the site for you — complete with free HTTPS and the option to connect your own custom domain later.

In this guide, you’ll learn exactly how to prepare your website files, create a GitHub repository, upload your site through the GitHub website (no command line required), and turn on GitHub Pages to publish it live. By the end, you’ll have a working public website and know how to update it any time you want.

Why Host a Static Website on GitHub Pages?

Before diving into the steps, it helps to know why so many beginners and professional developers choose GitHub Pages for static site hosting:

  • It’s completely free — there’s no hosting bill, even for a custom domain.
  • It includes free HTTPS — your site gets a secure padlock automatically.
  • It’s beginner-friendly — you can upload files directly through your browser, no command line needed.
  • It doubles as version control — every change to your site is saved in your GitHub repository’s history.
  • It’s reliable — GitHub Pages runs on GitHub’s infrastructure, so uptime isn’t something you need to manage yourself.

The trade-off is that GitHub Pages only hosts static sites — plain HTML, CSS, and JavaScript. If your project needs a server-side language like PHP or a database, you’ll need a different host. For portfolio sites, landing pages, documentation, and simple business sites, though, it’s hard to beat.

What You’ll Need Before You Start

  • A free GitHub account
  • Your website files: at minimum, an index.html file
  • A modern web browser

Step 1: Prepare Your Website Files

A simple static site typically uses a file structure like this:

my-website/
├── index.html
├── style.css
└── script.js

The file named index.html is important because GitHub Pages automatically loads it as your site’s homepage. Make sure it’s in the folder you choose as the publishing source in a later step.

Use Relative Paths, Not Absolute Paths

Keep your file paths relative so the site works correctly once it’s published:

<link rel="stylesheet" href="style.css">
<script src="script.js" defer></script>

Avoid leading slashes such as /style.css when your site will be published from a project repository. GitHub Pages project sites are published under a subfolder (your repository name), so an absolute path pointing to the domain root will break. Relative paths are more portable and will work regardless of the final URL structure.

Step 2: Create a GitHub Repository

  1. Sign in to GitHub.
  2. Select New repository from your account menu.
  3. Enter a repository name.
  4. Choose whether the repository should be public or private, based on your project’s needs.
  5. Select Create repository.

The repository name determines your site’s URL:

  • Personal user site — name the repository exactly after your GitHub username, in this format:
    username.github.io
  • Project site — use any other repository name, and GitHub will publish it at a URL like:
    https://username.github.io/repository-name/

Step 3: Upload Your Website Files

Open your new repository, select Add file, then choose Upload files. Drag index.html, style.css, script.js, and any image folders into the upload area.

Before committing your changes, double-check that:

  • index.html is included in the upload.
  • File and folder names use the same capitalization as the paths referenced in your HTML.
  • Images live inside the repository and are linked with relative paths.
  • No secret keys, passwords, or private configuration files are included.

Enter a short, clear commit message — something like Add website files — then select Commit changes.

Tip: For larger projects or sites you’ll update frequently, using Git from the command line is faster than uploading through the browser every time. See Mastering Git: Basic Commands for Version Control if you want to learn the command-line workflow.

Step 4: Enable GitHub Pages

  1. Open the repository’s Settings.
  2. Select Pages under Code and automation.
  3. Under Build and deployment, choose Deploy from a branch.
  4. Select the branch containing your website files, usually main.
  5. Select the folder that contains index.html, usually / (root).
  6. Select Save.

GitHub will display your site’s published URL once deployment finishes. The first deployment can take a minute or two. After that, any new commit to the selected branch will automatically republish the updated site — there’s no separate “deploy” button to click.

Step 5: Test Your Published Site

Open the URL shown in your repository’s Pages settings and click through it like a visitor would. Check:

  • Navigation links
  • Images and other assets
  • Stylesheets
  • JavaScript interactions
  • Mobile layout
  • Browser console errors (open developer tools and look at the Console tab)

If your site worked locally but something looks broken on GitHub Pages, the most common cause is file paths. A path like images/photo.jpg is relative to the current page’s location, while /images/photo.jpg starts from the domain root — and on a project site, that root includes your repository name.

Step 6: Add a Custom Domain (Optional)

GitHub Pages also supports custom domains at no extra cost. In your repository’s Pages settings, enter your domain under Custom domain and save it. Then add the DNS records GitHub requests at your domain registrar or DNS provider.

Once the DNS changes have propagated — which can take anywhere from a few minutes to 24 hours — return to the Pages settings and enable HTTPS when the option becomes available. Test both your custom domain and the original github.io URL before redirecting or removing anything, so you always have a working fallback.

Common Problems and How to Fix Them

The Page Shows a 404 Error

Confirm that the branch and folder you selected for publishing actually contain index.html. Also check that your repository’s Pages settings point to the correct branch and folder.

CSS or JavaScript Doesn’t Load

Check file names and paths carefully for spelling and capitalization mismatches. Confirm you’re using relative paths, and that the referenced files were actually included in your upload.

Images Are Missing

Make sure image files are inside the repository and that each src value matches the file’s exact location and capitalization. Avoid spaces and inconsistent capitalization in file names — they’re a common source of broken image links.

Changes Aren’t Showing Up

Check your latest commit and the deployment status under the Pages settings. Then refresh the page, or open it in a private/incognito browser window, since your browser may be showing you a cached version of the old site.

Conclusion

Hosting a static HTML website on GitHub Pages is one of the fastest, cheapest ways for a beginner web designer to get a real project live on the internet. All it takes is a GitHub repository, an index.html file in the right location, and a publishing source configured in your repository’s Pages settings — no hosting bill, no server management, and no command line required if you’d rather upload through the browser.

Once GitHub Pages is enabled, updating your site is as simple as committing new files to the selected branch; GitHub automatically republishes the live site for you. From here, you can layer on a custom domain, free HTTPS, and eventually a command-line Git workflow as your projects grow more complex.

Whether you’re publishing a portfolio, a landing page, or your very first coding project, now you know exactly how to host a static HTML website on GitHub Pages for free. For current options and limitations, see GitHub’s official GitHub Pages documentation and its guide to creating a GitHub Pages site.