Orestes Carracedo

Scrum Master, PHP Ninja, cat owner

1 posts archived under code.

09 June 2013

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

The cons

  • 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::Page and Jekyll:Generator. The method is pretty straightforward:

  1. Create a class that inherits from Jekyll:Page
  2. In the page class, implement the initialise method
  3. In the initialise method, call self.process(@name) and self.read_yaml to get the contents of the layout
  4. Add to the site.data Hash any data you want to expose to the page
  5. Create a class that inherits from Jekyll:Generator
  6. Implement the generate(site) method which adds instances of the custom page to the site.pages Array

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:

  1. Inherit from Jekyll::Site,
  2. Made an alias of the original site_payload
  3. In my site_payload method, called the original site_payload and get the returned data.
  4. 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 gh-pages branch.

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 a new 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 orestes.github.io.

Let’s check what’s going on with my domain name using nslookup.

$ nslookup blog.orestes.io

Non-authoritative answer:
blog.orestes.io	canonical name = orestes.github.io.
orestes.github.io	canonical name = github.map.fastly.net.
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.


Categories: technologies code
Comments: --