May 8, 2021
When I introduced my new website and blog I had several friends reach out and ask what technology I used. I told them I picked GitHub Pages, which they followed up with another question of why use that and not some other prebuilt solution. The decision was very easy to make - I’m a developer and I’m used to GitHub. GitHub Pages are free, made for developers, and are extremely easy to setup. You can literally have a site up and running in less than 20 minutes.
You might have noticed my site has a custom URL and not only does GitHub support this, they will generate a SSL certificate for the site based on your domain name for free. Below I will break down some rough notes I took when I went through the process for anyone looking to try to do this themselves.
I recommend using a code editor like Visual Studio Code to edit your site files and blog posts. It’s a great HTML and markdown editor. To compile pages, etc you will need some open source tools. On the Mac I use homebrew to install these and if I was using Windows I would use the Windows Subsystem for Linux to install Linux in Windows and then use the standard package manager in Linux or Chocolatey if you don’t feel that comfortable with Linux.
You will need the following tools on your computer:
Creating the site is as simple as creating a new repo in GitHub - although you must name it according to the GitHub documentation - which is usually username.github.io. The GitHub documentation is very good and I recommend fully reading it before attempting to create a GitHub Page.
Once my repo was created I cloned it on my local computer using SSH. NOTE I didn’t use there wizard to select a theme because I knew I wanted to hack something together based on a theme I could find on the internet so after I created the repo and named it I cloned it and decided to do the rest of the process manually.
My next step was looking for a theme I really liked on the internet. I googled for “free jekyll themes” and found several websites with resources. One of the more popular sites with themes is this one. Once I picked my theme I downloaded a copy of it and unzipped it to my hard drive into my downloads folder. I’m going to hack the crap out of it, so I always keep a backup copy of the original in case I need to compare the original to my hacked up version. Next I made a new folder in my repo for my github page called docs and I copied and pasted the files from the theme into that folder. Now it was off to the races hacking the HTML code.
The folder structure of the theme I’m using breaks down like this on my site:
The main page on the site is called index.html and I modified this to show off the design you see when you go to my main website.
The theme I downloaded had a file called _config.yml with all the configuration of the site including how to render the navigation menu. I went through and modified it’s code based on the readme file and reading the code.
Open a terminal int the directory where the _config.yml file is and run the following commands:
bundle exec jekyll serve
The first command will install any dependencies you need. The second command will start the webserver on your local machine and have Jekyll convert your MD files to static HTML files. You usually only need to run bundle install once and after that you can just run bundle exec jekyll serve when you want to debug any code changes you made on your local machine.
Publishing the site was as simple as going through and pushing my changes from my local computer to the GitHub Repo into the main branch. Once that was done I went into the repo settings from the GitHub portal and selected Pages from the menu on the left. This is where you can tell your GitHub Page setup which folder that your site is rendered in. Mine was in the docs folder so I configured it to use that.
Next was the tricky part of using a custom website name. I’ve always used Go Daddy for registering my domain name. I will note I really hate Go Daddy but they have extremely cheap prices and if you register a domain name the DNS hosting is usually free, which is what I needed. I would add you have to pay a fee every few years to keep your name reserved and pay for the DNS hosting - so this will be an on-going thing so make sure you pick a company that will be around.
What is DNS you ask? DNS or Domain Name System is the system that converts your website name to an IP address so your computer can find it (this is a very simple explication to a much more complex system). Entire books have been written and classes taught on DNS - so a single blog post isn’t going to make you an expert. Fun Fact: I used to be the Network Administrator of an ISP way back in the 90’s - so I know a lot more about DNS than the average developer. To make all this work I needed to create something called a CNAME record.
What a CNAME record does is take my website hostname which is www and domain name which is costoda.tech and point it to a different hostname and domain name, which is biozal.github.io. So when anyone on the internet browses to www.costoda.tech DNS will look at that name and see that it should instead go to biozal.github.io and sends your computer to that site instead. The nice thing about this is that your browser will still show my website as being www.costoda.tech, which is different than a redirect. I used the DNS manager on the Go Daddy website to setup this CNAME record. It isn’t terribly difficult to do and if you read your DNS hosting service documentation on how to create a CNAME it’s pretty straight forward - just point your new hostname which is www and your domain name to the full name of your GitHub pages site.
Once you have the CNAME record created - go back to GitHub and go into the settings of your repo and click the Pages link. You need to tell GitHub that you are using a custom domain name by typing that in and clicking Save. There is also a checkbox that states Enforce HTTPS - I highly recommend you check that and save the settings. GitHub will generate a custom SSL certificate for your site once it validates the configuration.
Now I will note that my GitHub page comes up with DNS warnings saying the zone records weren’t setup right when I know for a fact they are. I think this is a bug in the validation tool they have that validates your DNS hostname settings. My site is working without issues and you have confirmed that by reading this article.
And that’s how I setup my website. If you want to try this and you run into problems - hit me up on the Twitter and I’ll do what I can to help you out.