I’ve almost finished the migration of my old Posterous blog to Jekyll/Github Pages, and here are a few things I’ve leared:
Use the Docs
The documentation on Jekyll and Github Pages is great if you can find it. Here’s a cheat sheet for the most important documentation pages:
- YAML Front Matter - every post needs a YAML fonr matter block. This page lists what you can put in that block.
- Template Data - master reference of data that Jekyll makes available to the Liquid templating system.
- Liquid Tags and Filters - basics for how to use Liquid templating engine.
- Jekyll Liquid Extensions - Jekyll adds a few of its own Liquid templates, this page explains them.
Jekyll Dies Silently
When I was first playing around with my new site structure, Jekyll was quick to regenerate the site. After I migrated over my blog content (340+ posts with over 1000 images), Jekyll just stopped working altogether. It wouldn’t regenerate and it wouldn’t spit out any errors. I slowly discovered through trial and error that Jekyll couldn’t handle certain posts. So copying over pages one at a time (fun fun) allowed me to identify the problematic posts. I’m disappointed that Jekyll doesn’t provide any errors when it runs into a problem, it just stops regenerating your site without giving you any visible reason.
Multiple DNS Managers
This one is pure user-error but maybe it’ll save someone else a day of frustration. My domain is managed by Dreamhost, so when it came time to update my DNS to point at Github Pages instead of Posterous, I updated my DNS settings in Dreamhost and waited patiently. After 24 hours, nothing had happened so I went looking for a problem. After much ping’ing, tracert’ing and whois’ing, I finally realized that long, long ago I had setup Cloudflare and it was actually the real manager of my DNS settings. Once I turned off Cloudflare, my site was accessible at the new DNS settings in a few minutes.