Besides my writing skills, my problem with blogging was the software I was using, Wordpress. I found it slow, heavy and often insecure. I didn’t want my server exploding whenever I got a traffic spike, I didn’t want upgrading my WP modules and being worried about security issues. It was kind of hard to get it to look the way I wanted it. I wrote a custom theme but I wasn’t really satisfied with it, so I bought a one which looked cool, but I still wasn’t happy with my blog because it wasn’t “mine”.
I wanted a static blog website that I could code and style the way I wanted, without restrictions. I wouldn’t have to worry about security since it would be static and would have no user input, search or comment features. I didn’t want to give up comments so I checked Disqus, whichs a really good commenting platform that you can embed anywhere without having to worry about security or performance issues. Disqus is a seamless iframe whith a lot of clever programming inside. Ben Vinegar, gave a great talk about it in 2012: Seamless iframes: The future, today!.
Regarding the traffic spikes and server resources, I decided I’d move the blog out of my lab hosting (which is a tiny virtual machine) into somewhere that could serve static sites and I only had to worry about bandwith costs,
I started researching about scaffolding tools and generators for static websites. I had used stuff like yeoman that worked reat for getting something started quickly, but it was more aimed at apps than static websites and I’d still have to do a lot of the work.
Then I found about GitHub Pages and Jekyll, and they turned out to be the perfect solution for me. Jekyll is a blog-aware static website generator written in Ruby by Tom Preston-Werner. It’s easy to get started with and powerful enough to let you add your own plugins and teach it new tricks. GitHub Pages allows you to serve static content from your GitHub repositories without any setup
The pros Jekyll on GitHub Pages
- It’s already blog-aware, so it has a notion of posts, categories, tags and a timeline.
- I can version my posts and contents using a CVS I love (git)
- I can easily share the source code for my blog
- I don’t have to worry about hosting
- I can still use any domain name I own
- It provides higher geek factor than having a WP blog
- GitHub crashes every once in a while and maybe GH Pages comes down with it
Working with GitHub Pages
GitHub Pages are divided into user pages and project pages. The only thing you have to do is create a
gh-pages branch on your repository. Whatever you push to the branch will be served on your project page at
http://username.github.com/repository-name. If you push a Jekyll site, GitHub Pages will actually build the site for you and serve that instead of the Jekyll source.
Working with Jekyll
You create a new site running
jekyll new PATH which creates a bare minimum site config and layouts.
To create the extra tag and category index, as well as the archived month pages, I had to extend the same classes:
Jekyll:Generator. The method is pretty straightforward:
- Create a class that inherits from
- In the page class, implement the
- In the
initialise method, call
self.read_yaml to get the contents of the layout
- Add to the
site.data Hash any data you want to expose to the page
- Create a class that inherits from
- Implement the
generate(site) method which adds instances of the custom page to the
I generated the monthly archive by iterating over the
site.posts Array and analysing the dates. To generate the sidebar menu that displays the year/month list I needed to have an index to iterate over, so I coded my plugin
archive_helper. What I did was:
- Inherit from
- Made an alias of the original
- In my
site_payload method, called the original
site_payload and get the returned data.
- Added to
site.data Hash the indexes created from the posts’ dates.
The plugins to generate the tag and a category pages were already provided in the Jekyll plugin docs so I didn’t need to do any extra work.
You can get the source code for my plugins and all of this blog here
Deploying the site
The problem I had with my plugins is that GitHub pages builds the Jekyll sites using the
--safe switch, which disables them. The alternative is to push your source code to the
master branch and your generated site files to the
gh-pages branch. I didn’t want to do it manually every time I updated the source, so I wrote a little
post-commit hook that generates the site, wipes the
gh-pages branch and pushes the freshly generated site to the
Using a custom domain name
Everything gets served from
http://username.github.com/repository-name. Having a good grasp of the HTTP
protocol is crucial for a web developer, and I think we should also know at least a little about the DNS protocol. I
wanted to host my blog under
blog.orestes.io, so I got to my DNS panel on my domain registrar and added
CNAME DNS entry for
orestes.io with the name was
blog and the value
orestes.github.com. A CNAME is a Canonical Name entry, which tells
DNS clients asking where
blog.orestes.io is, to ask instead for
Let’s check what’s going on with my domain name using nslookup.
$ nslookup blog.orestes.io
blog.orestes.io canonical name = orestes.github.io.
orestes.github.io canonical name = github.map.fastly.net.
On the output above you can see how everything is being redirected to github.map.fastly.net
When you finally get to the HTTP server behind
github.map.fastly.net, it checks the HTTP 1.1 “Host” header, which is sent by the browser and will contain the value
blog.orestes.io. Then the GH Pages takes a look under the user’s projects and their /CNAME files to check if any of this projects is assigned to this domain. If there is, you get the static site, if there isn’t, a 404 error.