How to Host Your HTML, CSS & JS Website on GitHub Pages for Free — Step-by-Step Guide with Themes & Custom Domains

Dreaming of getting your personal portfolio, small business landing page, or side project online without spending a dime on hosting? Or maybe you want to publish a coded website for your school project or homework assignment. If your website is built with HTML, CSS, and JavaScript — a “static” website — then GitHub Pages is your golden ticket!

GitHub, known for collaborative coding and version control, offers a fantastic free hosting service for static sites. You can even use themes to style your site easily, and set up your own custom domain for a professional touch. While it involves a few extra steps compared to uploading files to a traditional web host, the benefits — like built-in version control, free HTTPS, and reliable performance — can make it worth the effort.

Let’s walk through exactly how to host your static website on GitHub Pages — including using themes and custom domains — step by step.

What is GitHub Pages?

GitHub Pages is a free static site hosting service offered by GitHub. It allows you to host your website directly from a GitHub repository. When you push changes to a designated branch (usually main or gh-pages), GitHub automatically builds and deploys your site, making your updates live within minutes.

💡 Note: A static website means it’s built with HTML, CSS, and JavaScript only — no server-side code like PHP or databases.

Types of GitHub Pages Sites: User/Organization vs Project

GitHub Pages supports two types of sites:

• User or Organization Site:
  You get one user or organization site per GitHub account or organization. This site must be hosted in a repository named exactly yourusername.github.io. Your entire site will live at
  https://yourusername.github.io/.
• Project Site:
  You can create unlimited project sites under your account or organization. These are repositories with any name you choose. Project sites are hosted at
  https://yourusername.github.io/project-repo-name/.

Prerequisites: What You’ll Need

Before you start, make sure you have:

• ✅ A GitHub account — sign up at github.com.
• ✅ Git installed on your computer — download it from git-scm.com.
• ✅ Your website files — HTML, CSS, JS, images, and other assets organized in one folder. Make sure your main page is named index.html.

Step-by-Step Guide to Hosting on GitHub Pages

Step 1: Create a New GitHub Repository

1. Log in to GitHub.
2. Click the New button (on the left sidebar or the “+” in the top right) and select New repository.
3. Set a name for your repository:
   • For a User/Organization Site: Name the repo exactly yourusername.github.io (replace with your GitHub username).
   • For a Project Site: Use any name you like, e.g., my-project.
4. Optionally, add a description.
5. Choose Public (GitHub Pages is free only for public repos).
6. Do not initialize with a README (we’ll push files manually).
7. Click Create repository.

Step 2: Initialize Git and Add Your Website Files Locally

1. Open Terminal (Mac/Linux) or Command Prompt (Windows).
2. Navigate to your website folder: cd /path/to/your/website/folder
3. Initialize a Git repository: git init
4. Add your website files: git add .
5. Commit the files: git commit -m "Initial commit: Add website files"

Step 3: Connect to GitHub and Push Your Files

1. Go to your new GitHub repository page.
2. Copy the HTTPS URL, which looks like:
   https://github.com/yourusername/your-repo-name.git
3. Add the remote origin: bashCopyEditgit remote add origin https://github.com/yourusername/your-repo-name.git
4. Rename the branch to main (if not already): git branch -M main
5. Push your files: git push -u origin main

Your files will now be on GitHub!

Step 4: Enable GitHub Pages

1. Go to your repository on GitHub.
2. Click Settings (top nav).
3. In the left sidebar, click Pages.
4. Under Source, choose the branch (main) and folder (/root or /docs if your site files are in a subfolder).
5. Click Save.
   GitHub will build and publish your site, usually within 5 minutes.

Step 5: Choose and Apply a Theme (Optional)

GitHub Pages supports built-in themes to style your site without much setup.

1. In your repository, create a file called _config.yml.
2. Add a theme line, for example: yamlCopyEdittheme: jekyll-theme-cayman
3. Commit and push this file to your repository.
4. Your site will refresh with the new theme applied.

You can explore more supported themes here.

Step 6: Access Your Live Website

• User/Organization Site:
  Your site will be live at:
  https://yourusername.github.io/
• Project Site:
  Your site will be live at:
  https://yourusername.github.io/your-repo-name/

You can also find the live URL in the GitHub Pages settings.

Optional: Set Up a Custom Domain

Want a custom domain like www.yoursite.com?

Both User/Organization sites and Project sites fully support custom domains, so you can personalize your website address regardless of the site type.

1. In GitHub Pages settings, under Custom domain, enter your domain name.
2. In your repository, create a CNAME file (uppercase, no file extension) with your domain name inside.
3. Update your domain registrar’s DNS records:
   • For www.yoursite.com, add a CNAME record pointing www → yourusername.github.io.
   • For root domains (e.g., yoursite.com), add A records pointing to these GitHub IPs: 185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153

🕒 DNS propagation can take up to 48 hours.

Benefits of Using GitHub Pages

• 💸 100% Free static site hosting
• 🚀 Fast & reliable, backed by GitHub’s global CDN
• 🔄 Version control with Git for easy updates and collaboration
• 🔧 Simple deployment — just push your changes
• 🌐 Support for custom domains
• 🔒 HTTPS enabled by default via Let’s Encrypt

Limitations to Know

• ❌ Static only — no server-side code like PHP, Python, or Node.js
• 📏 Repository and build limits (usually 1 GB repo size, soft build time limits)
• 🔒 Private sites require a paid GitHub plan

Let’s Recap

GitHub Pages is an amazing, cost-effective solution for developers, designers, and hobbyists who want to get a static website online fast. With built-in version control, instant deployments, free HTTPS, and support for themes and custom domains, it’s a free solution for portfolios, documentation, blogs, and simple web apps.

Give it a try — you might be surprised how quickly your site goes live!

If you want a traditional web hosting solution—with easy file uploads and full support for both static and dynamic sites—you can get started for under $5/month, with SSL included, through UltimateWB web hosting plans.