How to Host a Free Static Website with GitHub Pages
3 min read

How to Host a Free Static Website with GitHub Pages

How to Host a Free Static Website with GitHub Pages

With GitHub Pages you can host a free static website. This is useful for simple sites such as personal blogs or portfolio sites.

The information for this guide was taken from the official GitHub Documentation located here. If you prefer a more detailed explanation you can read it there however it can be a bit confusing and I provide examples for some of the parts that caused me problems such as setting up the DNS records.

Creating the Repository

The first step is to create a new public repository with the following name. You can do that using this link Make sure the entire repo name is lowercase.

Create a new GitHub Repository for our static site.
Create a new GitHub Repository for our static site.

You can change the remaining settings however you like.

Creating the Website

To test the site I added a basic index.html template to the repository.

<!DOCTYPE html>
<html lang="en">
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    Test Page

Now visiting https://<user> should show you the index page.

Using a Custom Domain (Optional)

DNS Settings

If you wanted to use a custom domain with your site you will need to create DNS records pointing to your repository.

These are my records I created using Google Domains

DNS Records
DNS Records

A Records

AAAA Records


CNAME Record


You can find more details regarding this topic on the GitHub docs located here.

Change Repository Settings

After creating the DNS records go back to your repository and go to Settings > Pages. You will want to enter your domain in the Custom domain field and click save.

Repository Pages Settings
Repository Pages Settings

After clicking save it will perform a DNS check to ensure your settings are correct. It can take up to an hour for the DNS records to update but for me it happened within a few minutes.

If you are unable to enable Enforce HTTPS you may need to wait for a few minutes then refresh the page.

Adding a Theme (Optional)

You can add a premade Jekyll theme to your repository from the Pages settings located at Settings > Pages.

GitHub Pages Theme Chooser
GitHub Pages Theme Chooser

This will add a basic theme to all Markdown files in the repository. For details on how to customize the layout of these pages refer to the Jekyll Documentation.

To add the theme to our index.html page you need to add the Jekyll Front Matter to the top of the file.

layout: default
title: Home Page

The index page should now have the theme applied.

Index Page with Theme Applied
Index Page with Theme Applied


Here are some other useful guides you can use to create your website.