How to not make a blog, or how I stopped worrying and love breaking stuff.

Posted on Mon 09 May 2016 in blog

Hello there!

These are my thoughts on trying to build a blog with the latest "cool" thing called GithubPages + Jekyll.

If you have never heard about it before, it's basically using "free" web hosting on GithubPages plus a static website generator engine called Jekyll.

There are many great tutorials to get you started, one being an official Jekyll Guide which gives an overview of how to integrate the two and a second one, the more analytical by Jonathan McGlone.

However having Jekyll on its own does not really help with making a blog that looks nice, especially if you're a developer like me who has no idea how to design anything better than a napkin.

So what does anyone do when need something? Ask our Supreme Overlord Google for a nice theme. The one I found that I really liked was Hyde. It's a two column theme that was pretty much what I was looking for.

I just went ahead, and put everything together, trying to make it work. Usually that's not the proper way to do something in a professional setting, however when trying out a new project I think this is a better way to get a good understanding of how different parts come together.

How to do it wrong

To dive right in I downloaded Jekyll and created a new site. Then begun the hard part. How do I integrate Hyde? Hyde is itself built upon a set of foundation setup called Poole, however Hyde already contains all Poole code that is needed so I decided to just head over to the Hyde codebase and try to copy all code tha seemed relevant. After a bit of back and forth and deleting what I thought was not needed/I didn't want on my blog I thought I was ready to go.

The major problem I encountered was that the blog would stubbornly not show any blog posts.

Turns out I was missing the paginate gem (Jekyll engine is based on ruby) and also two necessary config items.

After a lot of search, and feedback from Google I managed to get it working.

Note to self: Code on config files is usually necessay, do not delete without checking the outcome.

The next challenge encountered was how to integrate a custom domain name. GithubPages already provide the [username] url for the page, where [username] is your github one, however I always wanted a customer domain and now was the time to get it.

Everyone knows the basics of how domains work: you have a server that matches URLS to IPs however how do you actually make assign one to the other?

A(ddress) and CNAME Records

A-records are basically mappings that return a 32-bit IPv4 address. They are used by your domain registrar to let them know where you want the URL you just bought though them to direct to.

In our case Github provides two IP addresses to map to. However how does Github know which site (Github URL) to direct the request to?

Enter CNAME records. As described by wikipedia:

A Canonical Name record (abbreviated as CNAME record) is a type of resource record in the Domain Name System (DNS) used to specify that a domain name is an alias for another domain, the "canonical" domain. All information, including subdomains, IP addresses, etc., are defined by the canonical domain.

So what we are basically doing with this file is map the external URL (in my case to the internal URL that Github knows

Is the hassle worth it?

So enough with the rant, was it actually worth it?

That's not a straightfoward answer. There are currently far easier ways to start a blog (Wordpress, Medium etc), why go through all the hassle to make it from scratch?

Well, what drew me to Jekyll is that as a developer I'm always enjoying more building stuff myself. Having exposure to the underlying code is always a great strength that allows you to configure (and also break) a project, and also provide valuable knowledge.

So take something apart, break it and then try to make it work. You will always be more motivated to make it work again. Go break stuff!