Peter Goodman bio photo

Peter Goodman

A developer living in Auckland building software using all sorts of bits and pieces I find along the way. Originally from Northern Ireland.

Twitter Google+ LinkedIn Github

GitHub Pages

Like most of the bloggers on the internet these days I’ve moved my blog off wordpress and onto GitHub pages using Jekyll.

There was a fairly large amount of Yak Shaving involved in this process. I’m not going to do a tutorial on how to move from Wordpress to Pages/Jekyll, you can find plenty of info on how to do that on the links below. I will however point out some of the things that threw me.

  • This is a good tutorial by Hadi Hariri
  • Follow the Jekyll migrations site for instructions on exporting the Wordpress XML. (The Wordpress plugin didn’t work for me)
  • Learn that Windows is a second class citizen in this toolset and you are going to have to shave some Yaks.
  • Make sure you install Ruby, Jekyll, Bundler
  • Set up your GitHub pages repo.
  • Choose a theme and pull it into your repo. Decide whether you are going to fork it or just pull it into your existing repo.
  • When importing ignore the Jekyll import site bash script and just use jekyll import wordpressdotcom --source wordpress.xml instead
  • Make sure to add the correct encoding for your site if you are on Windows.
  • Watch out for the problem with “{{” characters in your xaml. Broken by Liquid 2.0. Fixable by escaping.
  • Remember to keep changing the url in the _config.yml to suit your current deployment or strange things might happen.
  • DO NOT waste time trying to get FrontMatter defaults working. I couldn’t and gave up. Wasted sooooo much time on this. Instead I just changed the template to always switch on Disqus comments on posts.
  • Disqus support admitted that they currently have a problem with their import, hence my old comments are not there yet.
  • Learn to get permalinks right and use the jekyll-redirect-from plugin which GitHub pages supports.
  • Worst of all is the rss feed. My previous blog’s feed was at /index.php/feed/ while the default templates for jekyll puts it at /feed.xml. This wouldn’t be too hard but the redirect plugin for jekyll uses html based redirects rather than proper 301s, Feedly only likes 301s. Add to that the fact that GitHub pages doesn’t do .htaccess files and you have a recipe for disaster. Luckily there is a hack, create an index.php folder and a feed folder and inside put a copy of the feed.xml file renamed to index.html. Although the content-type of the feed response is now text/html it seems to work none-the-less.

Good Luck!