Host Website on GitHub Pages (The Easy Way)

Ever since my first class on web development, I have loved making websites. I loved the classes, I loved learning about HTML, CSS, and JavaScript. I loved everything about it, except when it came time for publishing a website. Sure, it was nice that you can make a site, but what good is it if you can't access it on any computer. Those classes went in to this big thing on how to get a free trial from some company, that has these complex server setups, and a FTP setup that you need to configure, and then after all these steps, which you are never going to remember, you have a website. So the purpose of this post is to publish a basic static website for beginners for free with minimal setup.

GitHub

If you aren't familiar with GitHub, you should look into it. I am not going to go in depth with it here, but just know that if you are writing code, it would be worth your while to set up some version control with Git. GitHub is like your cloud storage for your code, except that you can also choose to host a static website from it as well. So if you haven't set up your GitHub account, do that first.

Create a repository

When you are in GitHub, create a new repository. For those of you who are new to this, a repository is basically just a new project. If your end goal is to host one site, you probably want to host your website at the root of your account. The URL for your site will be <username>.github.io. When setting up your repository, your repository name should be <username>.github.io so GitHub knows that you want to host this file at the root. I would recommend this for the first site you create. You can always change this later. If you name your repository anything else, like easy-hosting your site will be hosted at <username>.github.io/easy-hosting. This second example could have some issues if you ever use absolute links (ex. <a href="/about">About</a>). That will be looking for the page <username>.github.io/about rather than <username>.github.io/easy-hosting/about. We will get to a fix for this in a second.

Whichever direction you go, make sure that you use a public repository. You cannot host a website on GitHub in the free tier using a private repository.

Adding code to GitHub

There are three pretty easy ways to add code to GitHub. The first way is not what I recommend, but you can still do it. You can upload your code from your computer and just stick it in the repository. This gets clunky very fast, and is a pain to work with. Don't do this.

GitHub Desktop

The second way is to use GitHub Desktop which is a desktop application that handles all of your git commands for you, and can link your local files on your computer to your GitHub account online. When I first started with Git, I didn't know a single thing about the command line like traditional Git courses teach you. I got along just fine for a few years because of GitHub Desktop.

If you go this route, and have GitHub Desktop setup, you can choose from GitHub's website to set this repository up on your local machine from GitHub Desktop. From there it is pretty much straight forward. The app will set up your repository on your local machine and you can put your code there. Then it is just a matter of pushing your code up to your GitHub repository online.

Visual Studio Code

The third way, and my preferred way is to use Visual Studio Code. I write all my code in VS Code and love it. VS Code has a built-in Git user interface, so like GitHub Desktop, you don't need to use the command line for simple things. In the bottom left corner of the window, you can log in to your GitHub account. Sign in there. The default editor will also have more icons on the top right, and you can manage your git integration on the third one down titled "Source Control". This is very similar to GitHub Desktop, except that you don't need to leave your editor to do anything.

From here you may just need to clone your repository using the command line. Follow the instructions in the GitHub repository that you set up.

A Little Background

Those steps were a little vague, so you may need some additional help from other blogs or videos to get your code online. The point was to get your HTML files and other assets in your online repository from your local machine. Now here is where I feel like this post is different than most other tutorials. A few years ago the only way to host a site on GitHub was to have a branch called gh-pages and if you set it up, it would use files on that branch for hosting. Then they let you use your master branch as well, but only what was in the /docs directory. That isn't the case anymore. You can now use any branch, and you can use the root of that branch or the docs directory. Unfortunately, at the time of this writing, you can't choose a specific folder for hosting.

Set up Hosting

At this point, you should have a repository, a branch (probably main), and at the very minimum an index.html file in the root of the repository.

1. Go to your repository's settings.
2. In the left navigation, near the bottom, click on "Pages".
3. Under the "Source", change it from none to your branch (probably main). Leave the folder at root.
4. Save the setting. You should see a new popup that says Your site is ready to be published at https://<username>.github.io/easy-hosting/.

Your site is now live! Any time that you commit and push your code to GitHub on the same branch, your website will automatically update. It's pretty slick.

The following sections are extra information that you may or may not need, but would be good to know about.

Custom Domain

This setup I just explained got me by for a while, but remember how I mentioned absolute links? Wouldn't it be nice to setup your own custom domain and subdomains rather than subfolders? Well, you can, and it is very easy.

If you use a custom domain, be prepared to pay for it every year. It is about $12 on the low end. It isn't much, but just be aware of this.

I choose to purchase my domains from Google Domains. Go find a domain and purchase it. Once you have it purchased, go into its configuration and find "DNS" in the left navigation. Enter the following configuration so that it matches:

In short, the first line is your domain mapped to GitHub's servers. The second uses the www subdomain, which is pretty common. The third is to have your own subdomain. This is especially helpful for repositories like our easy-hosting repository. If we host our site on easy-hosting.<domain>.com, we can use absolute links, which will point absolute links to where we would expect it.

There is one more step to get this to work. We need to go back to GitHub and in our Pages setting. Below the branch you entered earlier, there is a section for a Custom Domain. Enter your custom domain (<sub>.<domain>.com or <domain>.com) and save it. If you go back to your repository home page and look at your code, you will see that it created a CNAME file in it with your custom domain in it. That is really all the setup that you need. It might take 20 minutes to a few hours for GitHub to configure some things in the backend. So go take a walk or something.

Static Site Generators and Single Page Applications

Maybe you really don't want to spend a penny on this, but want to use absolute links in your project. Well, there is another workaround for this, but it takes a little more experience, and I won't really cover it much here. If you are building a serious website, you are hopefully at least using a static site generator like 11ty, Nuxt, or just a single page application tool like Vue. Each of these have ways to set the root of your project using a path prefix. Here is 11ty's configuration, Nuxt's configuration, and Vue's configuration. I am sure if you are using something else, it will have a similar configuration for you.

Changing those configurations will allow you to use absolute links, and still host your site on <username>.github.io/<repository>.

While we are talking about this, because GitHub will only allow you to host from the root or docs directory, you would also want to configure your tool to output your files to the docs directory. For example, 11ty will generate the files to the _site directory, and Nuxt will output the files to the dist directory. You can get around that with 11ty's configuration, Nuxt's configuration, and Vue's configuration.

Conclusion

Hopefully some parts of this have helped some of you out there. I can't say that GitHub pages is the best place to host a website, but for beginner projects, it is the perfect place to start. It is free, easy, and configurable. If you have any questions, just let me know if the comments.