In building the new site, I decided to take the opportunity to try out something new. I’ve been using WordPress to power my blog for about 5 years, and while it has served me well, I wanted to try out something different. The main criteria for choosing a new blogging platform were :
- It should serve true static pages, with no need for server-side processing.
- It should be easy to store the entire site in Git.
- It should support the concept of layouts - I wanted to have a single ‘template’ file that blog posts could easily inherit from.
- It should support MarkDown or Textile for formatting posts, since I want to keep away from posting raw HTML as much as possible.
- It should support comments.
- I should be able to deploy updates to the site with a single command.
By patching together a few different open-source technologies, I’ve been able to achieve the above and more.
After trying out several different static site generators, I settled on Jekyll. In its own words :
Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server.
Jekyll has a healthy community built around it, and has a plugin system, which I figured would allow me to work around any shortcomings I came across. The fact that Jekyll is used to power GitHub Pages also helped sway my decision, since I know it isn’t going to go away anytime soon.
Custom Jekyll Plugins
I ended up writing several custom Jekyll plugins to provide things that aren’t included by default :
- A short generator to create a google-compatible XML sitemap automatically.
- A generator to create category pages automatically (for example the Ruby category).
- A more in-depth generator that takes git repositories, and automatically builds project pages for them using the README file, along with downloadable zipped copies of the projects themselves (for example, the jquery-simple-color plugin page). I only have a couple of these projects up at this point, but have quite a few queued up to release when time permits, so I wanted the process to be automated as much as possible.
The plugin documentation is a little sparse, but there are a couple of examples to get you going. I’ll be releasing the source of my own custom generators over the next couple of weeks, so stay tuned to RSS if you want more information.
Since this is the first site I’ve built with HTML5, I decided to use HTML5 Boilerplate as a starting-point, which bills itself as the professional badass’s base HTML/CSS/JS template for a fast, robust and future-proof site .
Overall it works very nicely, although things still look a bit wacky on Internet Explorer (my fault, not BoilerPlate’s). We’re serving the site with Nginx, so we miss out on some of the Apache .htaccess goodness that comes with HTML Boilerplate, but overall it’s nice and easy to dive in and get started with.
One minor niggle is that the meta tag for triggering Google Chrome Frame in IE doesn’t validate, which doesn’t really affect anything one way or the other, but it’s always nice to get the green tick from validator.w3.org.
Compass is a stylesheet authoring framework that makes your stylesheets and markup easier to build and maintain. With compass, you write your stylesheets in Sass instead of CSS. Using the power of Sass Mixins and the Compass community, you can apply battle-tested styles from frameworks like Blueprint to your stylesheets instead of your markup.
The Compass/Sass combo is a huge time-saver when building CSS-heavy sites, and even on a reasonably minimal site like this it helps keep things nicely organized, readable and maintainable. Compass was relatively easy to get running with Jekyll - Bjorn Arild Maland has a few tips that helped here.
The fact that Compass was designed to work with ruby/rails was an added bonus here, since it allowed me to handle all common Jekyll and Compass tasks in the same Rakefile.
Jekyll uses Pygments to do code syntax highlighting. Again I was pleasantly surprised how easy this was to integrate, since it’s written in Python rather than Ruby. Installation on Leopard is as simple as :
Once it is installed, you need to generate the CSS required for highlighting :
This generates the default color scheme, and drops it into a folder inside sass (you may want to organize your SASS files differently). Once you have the CSS installed, you can highlight code in your posts by wrapping it in highlight_ tags :
1 2 3
Pygments supports a bunch of languages, and it doesn’t look terribly difficult to add your own if the need arises.
Being a huge fan of automation, I used Rake to script some of the common tasks involved with running the site. These shortcuts handle tasks like compiling the CSS, compiling the HTML, cleaning all build products, generating pygments CSS, and deploying the site.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
I’ve used Capistrano on several projects in the past, and was very keen to use it again.
Capistrano is an open source tool for running scripts on multiple servers; its main use is deploying web applications. It automates the process of making a new version of an application available on one or more web servers, including supporting tasks such as changing databases.
Again, Capistrano was very easy to get going with Jekyll. I had to write a simple deploy.rb script to push the site to production :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
… and a supporting production.rb file :
1 2 3 4
… as well as a passwords.yml containing login information for the production server.
Once Capsitrano and Rake are set up, deployment is as simple as doing a
This cleans out all the old build products, rebuilds the site and associated CSS, grabs all my projects from Git, builds pages for them and adds a link to the latest zipped-up version, and pushes everything to the production server.
My only gripe with the service is that it has proved impossible to import all the comments from the old WordPress site into Disqus - I’ve tried their WordPress plugin, a direct upload of the XML exported by WordPress, as well as a site crawl, and nothing seems to have worked. I haven’t gotten around to contacting them about this yet, so possibly there’s a simple way to do it that I’m missing. For new content though, Disqus works great.
Once again I’m using FeedBurner to serve the RSS feed - it gives some nice stats, and looks a little better than a plain feed. Again, this was fairly straightforward to get running with Jekyll - I posted a how-to several weeks ago laying out how to get it all going.
So what’s the verdict?
With services like Disqus appearing, pure-static sites are now a viable option for blogging. I love being able to write in a regular text editor instead of the WordPress WYSIWYG editor, and love the safety-net that keeping everything in Git provides. Jekyll is extremely light-weight and pluggable - I don’t think getting Compass and Pygments going with WordPress would have been quite as straightforward.
Re-building the site (and researching the various options beforehand) really drove home to me how many great, open-source projects there are these days - the fact that I could just plug in all these disparate pieces to build a site in a weekend was a pleasant surprise.