Github

How to Host a Static HTML Website for Free with GitHub Pages

April 17, 2026 7 min read By pixoptimo@gmail.com
How to Host a Static HTML Website for Free with GitHub Pages

If you have built a website using HTML, CSS, and JavaScript, you can host it for free with GitHub Pages.

It is one of the easiest ways to publish a simple website online. You do not need paid hosting. You also do not need a server setup.

GitHub Pages works best for:

  • personal websites
  • portfolios
  • landing pages
  • documentation pages
  • simple frontend projects

In this guide, you will learn:

  • what GitHub Pages supports
  • how to prepare your files
  • how to upload and publish your site
  • how the URL works
  • how to use a custom domain

Quick Summary

Here is the short version:

  • GitHub Pages lets you host static websites for free
  • It supports HTML, CSS, JavaScript, and Markdown
  • Your main file should usually be index.html
  • You can publish from:
    • the repository root (/)
    • or the /docs folder
  • It does not support backend code like:
    • PHP
    • Python servers
    • Node.js apps
  • You can also connect a custom domain

What GitHub Pages Supports

GitHub Pages is made for static websites.

That means it can host files like:

  • HTML
  • CSS
  • JavaScript
  • images
  • folders like assets

It can also use these as the main entry file:

  • index.html
  • index.md
  • README.md

For a normal website, the best choice is:

  • index.html

That is the standard homepage file for most static websites.

Important

If you publish from a branch and folder, your main file must be at the top level of that folder.

Before You Start

Before you upload anything, make sure your website files are ready.

For a normal static website:

  • your homepage file should be named index.html
  • if you publish from the root, keep it in the root
  • if you publish from /docs, keep it inside the docs folder

Example Website Structure

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

This is a common and clean structure for GitHub Pages.

Step 1: Create a GitHub Repository

First, log in to GitHub.

Then create a new repository.

You can name it something simple like:

  • my-website
  • portfolio-site
  • landing-page

If you want the easiest public setup, choose a public repository.

That is usually the best option for a basic GitHub Pages website.

Step 2: Upload Your Website Files

Open your new repository.

Upload all your website files, including:

  • index.html
  • CSS files
  • JavaScript files
  • images
  • asset folders

Then commit the files to the branch you want to publish from.

Most people use:

  • main

If you already use Git locally, you can also push the files from your computer.

Step 3: Open GitHub Pages Settings

After uploading your files:

  • go to your repository
  • click Settings
  • open the Pages section

Inside the Pages settings, you will see the Build and deployment options.

This is where you tell GitHub how to publish your site.

Step 4: Choose the Publishing Source

For beginners, the easiest method is:

  • Deploy from a branch

Then choose:

  • your branch (usually main)
  • your folder:
    • / (root) if your index.html is in the root
    • /docs if your files are inside the docs folder

Then click Save.

Once you save it, GitHub starts building and publishing your website.

Step 5: Wait for the Site to Go Live

After saving the Pages settings, GitHub will start the deployment.

This usually takes a few minutes.

Sometimes it can take up to about 10 minutes after changes are pushed.

So if your website does not open immediately, wait a little and refresh later.

Step 6: Open Your Live Website URL

After the deployment is ready, GitHub will show your live website URL inside the Pages settings.

The final URL depends on your repository name.

If your repository name is exactly:

your-username.github.io

Then your website URL will be:

https://your-username.github.io

This is called a user site.

If your repository name is something else, like:

my-website

Then your website URL will usually be:

https://your-username.github.io/my-website

This is called a project site.

This is very important because many beginners expect the website to open from the root domain, but it may include the repository name in the URL.

Can You Use a Custom Domain?

Yes, you can.

GitHub Pages supports custom domains.

That means you can connect your own domain, such as:

  • www.yourdomain.com
  • docs.yourdomain.com

How to add a custom domain

Inside the Pages settings:

  • find the Custom domain section
  • enter your domain name
  • save the settings

In some cases, GitHub may create a CNAME file automatically when you use branch-based publishing.

For Detailed Explaination Check Below Link:

How to Connect a Custom Domain to GitHub Pages (Simple Guide)

Important

After adding the domain in GitHub, you still need to update your DNS settings with your domain registrar.

This step is required so your domain points to GitHub Pages correctly.

Once the domain is connected, GitHub can also help with:

  • HTTPS
  • domain verification
  • domain management settings

Important Limitation of GitHub Pages

GitHub Pages only supports static content.

That means it does not run backend or server-side code.

It does not support things like:

  • PHP
  • Python backend apps
  • Node.js servers
  • Express
  • Laravel
  • Django
  • database-based websites

So GitHub Pages is best for:

  • static websites
  • frontend-only projects
  • portfolio sites
  • landing pages
  • documentation sites
  • small demo projects

If your site needs a database, login system, or server logic, you will need another hosting option.

Best Use Cases for GitHub Pages

GitHub Pages is a great choice for:

  • portfolio websites
  • student projects
  • resume websites
  • personal landing pages
  • documentation pages
  • frontend practice projects
  • HTML/CSS/JS demos
  • GitHub project showcase pages

If your site is simple and frontend-only, GitHub Pages is a very good free option.

Common Beginner Mistakes to Avoid

Here are a few mistakes people often make:

1. The homepage is not named index.html

If your main file is not named correctly, the website may not load as expected.

2. The file is in the wrong folder

If you choose /docs, your index.html must be inside the docs folder.

3. Wrong publishing source

If you select the wrong branch or folder, GitHub Pages will not publish the right files.

4. Expecting backend support

GitHub Pages is only for static websites. It will not run PHP or server-based apps.

5. Not waiting for deployment

Sometimes the site takes a few minutes to go live after publishing.

Final Thoughts

If you want to host a simple HTML website for free, GitHub Pages is one of the easiest options.

It is beginner-friendly, free, and works very well for static websites.

Just remember these basics:

  • use index.html
  • upload all your frontend files
  • choose the correct branch and folder
  • wait for deployment
  • use a custom domain if needed
  • do not expect backend support

If your website is built with HTML, CSS, and JavaScript, GitHub Pages is a great place to publish it.

GitHub official beginner tutorial: https://www.youtube.com/watch?v=b2r9Cdvssi0 

FAQ

Is GitHub Pages free?

Yes. GitHub Pages can host static websites for free.

Can I host an HTML website on GitHub Pages?

Yes. It works very well for HTML, CSS, and JavaScript websites.

Can GitHub Pages run PHP?

No. GitHub Pages does not support PHP or other server-side code.

Why is my website URL showing the repository name?

That usually means your site is published as a project site, not a user site.

Can I connect my own domain to GitHub Pages?

Yes. GitHub Pages supports custom domains.

← Previous Article What Is JavaScript Minification and How Does It Work?
Next Article → How to Minify CSS Online in Seconds (Free & Easy Guide)