This (almost free) blog

One of my resolutions this year was to start reading and blogging more. I have had this blog for about two years now but haven’t really made much use of it. That’s fine because it costs me almost nothing to run it. However, in the spirit of my resolution I wrote this post on how I set up this blog and how you could do it too.

Free Hosting from Github

To start with, this blog is hosted by GitHub Pages. This means that it is backed by a standard git repository on GitHub where I commit my posts. This has one advantage and one disadvantage. The advantage is that you can write version-controlled posts with git (duh). The disadvantage is that all your posts are public even before you publish them (unless you have a paid account with GitHub).

To set up Github Pages just create a new repository called {username} and commit some HTML files. These will then be served by GitHub on http://{username}

This blog on GitHub

I write my posts in Markdown and they are later converted to HTML with a static page generator by GitHub. There are several static-page generators out there but as a Ruby shop GitHub are keen on Jekyll.

Jekyll the Static Site Generator

Documentation for Jekyll is decent so there’s not much point for me to go over how it works but the three basic commands are:

  • jekyll new PATH - creates a new Jekyll project in PATH
  • jekyll build - converts your Markdown files to HTML
  • jekyll serve - runs a small server that serves your HTML content as you write it

And that’s it really. If you’re feeling adventurous you can write your own theme and even add some Javascript to it but I am by nature a lazy person. So I started googling for already existing themes. I always liked the look of the default Ghost theme Casper. Since the theme is open-source there was already a Jekyll port called Jasper - perfect. Props to the author Fábio Madeira and the Ghost team 👏.

If you haven’t heard about Ghost it’s an open-source blogging platform (similar to Wordpress). You can run it on your own server or get a paid Ghost account but either way it’s going to cost you something which is why I opted for GitHub Pages + Jekyll.

Custom Domain

The last thing every good blog needs is a custom domain. I originally bought my domain from GoDaddy for about £2 but after I learned about their advertising and their CEO killing elephants on video I transferred to Namecheap. The custom domain is the only thing that actually costs me anything and the cost is about one beer a year.

To set up DNS for your custom domain you need to create two A records with host @ pointing to GitHub’s DNS Servers (as of now and and a CNAME Record with host www and target {username} The very last thing you need to do is to create a file in the top level of your repository called CNAME with the domain in it - in my case.

A Recods and CNAME Record with Namecheap

What next?

There are two ways you can set up Jekyll with Github Pages:

  1. You let GitHub generate the HTML files for you
  2. You generate the HTML files yourself (or with a CI tool)

Again out of laziness, I went for option 1 but have started considering option 2 recently. It turns out that GitHub overrides some of the Jekyll configuration and won’t run your custom Jekyll plugins (understandably). Plugins are interesting - you could write a plugin that generates HTML at say tags/clojure for all your posts tagged clojure. Jasper actually supports this by default but I turned it off for now.

If you’d rather not leave the page-building to GitHub you can jekyll build the blog yourself and commit the output to a special branch in your repository called gh-pages. More info on that here.

Another option is to use a continuous integration (CI) tool like Travis CI or Circle CI - both of which have free accounts that allow you to re-build your blog whenever you push with git (basically automate the above). I haven’t done this myself so I’m not going to describe the details but might in the near future (another blog post? yay!).

Oh by the way, the header images come from and are released under CC0 license.