One day recently, I decided to start a blog. I’ve tried this several times in the past but the project always seems to die when it comes to figuring out what technology to use or how to host it.
I’ve tried several platforms; Wordpress, Blogger, and even building the Classic Rails Blog™️ more than once. All of those solutions seem to require a ton of work just to maintain the site. What I really want is something that is easy to set up, host, and will allow me to spend time on more interesting problems.
GitHub Pages to the rescue!
came to my attention and at first glance it seemed easy to use so I decided to try it out. GitHub offers an automatic page generator for Pages sites that you can access in
Settings > Options > GitHub Pages but this doesn’t seem to offer as much flexibility for the theme and layout of the site as I wanted.
Fortunately, GitHub Pages has support for Jekyll which is a static site generator with support for writing blogs in Markdown.
Here’s what I had to do to make this work:
Setting up a GitHub Page
The first thing I did to set this up was to create a git repo named
In my case this was
thetizzo.github.io. It is important to make sure that your username is spelled correctly and the name of the repo matches this format or GitHub Pages will not display the site correctly.
For personal GitHub Pages, the site will automatically be served using the master branch of this repository. It’s shocking how quickly changes will show up on the actual site once you push them to GitHub. It often doesn’t take more than a few seconds.
Setting up Jekyll
To get Jekyll set up I ran these 3 steps:
At this point you can go to
localhost:4000 and see the default Jekyll site.
Integrating a theme
If you want, you can start writing blogs posts right away, but I wanted to change the theme of the site make it my own. Jekyll lets you build anything so you could use Sass to design the site any way you want or you can download a pre-made theme, which are available from several places.
I decided to use a pre-made theme because I figured that working through integrating that theme with my site would be a great way to gain a better understanding of how to work with Jekyll.
This theme is set up to be it’s own standalone site so in order to integrate it I started by setting up a new page that would use a separate layout from the rest of the site. To add a new page to the site you just need to add an HTML file to the project root. In my case this was
resume.html which looks like this:
That’s really it. In Jekyll, anything at the top of a file between the dashes is called Front Matter and can be used to pass variables and defaults into a page.
Since I’m using a theme, I just need the front matter for
resume.html to point to the
_layouts/resume.html layout file which will end up being the place where the bulk of the page structure is.
I then copied over the rest of the theme to the appropriate places, making sure to namespace all the files to keep the two different themes (default and resume) separate until I was ready to combine them. It looked something like this:
resume-template -> my_project _config.yml contents -> _config.yml _layouts/resume.html -> _layouts/resume.html css/main.scss -> css/resume-main.scss _sass/*.scss -> _sass/resume-*.scss _includes/*.html -> _includes/resume-*.html
I was then able to build a resume page using this theme while leaving the rest of the existing site alone. Once that was finished, I merged the styles from the resume page into the default layout by removing the default theme styles and removing the namespace for the resume styles and files so they would apply everywhere on the site.
Using Font Awesome with Jekyll
I personally love Font Awesome. If you haven’t heard of Font Awesome, it’s a set of icons that you can easily include in your site. They are included as a font to your site so you can easily customize them with CSS.
Font Awesome offers a CDN to serve the assets so including them in a project is super easy. I simply added the following line to
Setting up a custom domain
Another nice thing about GitHub Pages is that they offer a super easy way to put your own custom domain on the site. This is nice because it gives you the performance benefits of GitHub’s CDN but also let’s the site have the feel of a completely custom website.
I will let GitHub’s own instructions
speak for themselves on this matter but basically all I had to do was add a CNAME record through my DNS provider for
thetizzo.com to point at
thetizzo.github.io and add a file called
CNAME to the root of the project that looks like this.
Adding Google Analytics
To add Google Analytics to the site I created a file,
_includes/google_analytics.html, and put in the code snippet that Google gives you when you sign up for Analytics which looks something like this:
Then included that file in
This isn’t strictly necessary because the code for the site is all public anyway but it’s more fun to have an HTTPS site.
For the rest of the set up I followed this post and everything went swimmingly. Once everything was set up it took a couple hours for the SSL to be provisioned and the Page Rules to take affect.
Hopefully this was helpful. Good luck and have fun with your new, highly advanced GitHub page.