I decided to switch my blog from FunnelWeb to Jekyll and host it on GitHub Pages. There were some problems along the way so I'm documenting it here in case it might help someone. If you want a more detailed introduction to Jekyll, read Brian Rinaldi's Getting Started with Jekyll post.
Installing Jekyll on Windows
Since I'm not a designer, I decided to choose one of many Jekyll themes and modify if necessary. Changing the theme directly on GitHub would be clumsy, since a lot of files are involved. Also doing little changes and testing the outcome would require a lot of git commits. Instead, I cloned my repository locally and installed Jekyll and its requirements on my Windows machine.
There's a very good tutorial for installing Jekyll on Windows. Unfortunately it's a little bit older. I followed the guide and installed the latest version of x64 build of Ruby, Ruby DevKit, Jekyll, x64 build of Python and Pygments. The latest Ruby version at the time of writing was 2.2.1.
It looked like everything went smoothly, but when trying to run Jekyll serve on my blog repository, it failed. The problem was with one of the Ruby gems called nokogiri. Apparently, it doesn't work with Ruby 2.2.1 on Windows, so I had to fall back to older Ruby version - 2.1.5.
Of course, something had to go wrong with that too. After installing Ruby 2.1.5 x64 and Ruby DevKit, gem installation with the following message:
gem install jekyll
ERROR: Could not find a valid gem 'jekyll' (>= 0), here is why:
Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed (https://api.rubygems.org/latest_specs.4.8.gz)
This SO answer helped and I was able to install Jekyll after that.
Since I'm referencing few Ruby gems in _config.yml I had to install those too:
gem install jekyll-sitemap
gem install jekyll-redirect-from
gem install jemoji
Finally, running the following command started the build process and enabled file change watcher. Success!
jekyll serve --watch
I tested several themes locally, before settling up with Pixyll theme.
Creating user repository
There's an easy getting started guide on Smashing Magazine. I ended up with user repository forked from John Otander's Pixyll theme, instead of Jekyll Now that's described in the guide above.
In _config.yml file permalink is set to pretty. That's what I want it to be, since I prefer to have date in URL and no extension. My blog posts didn't have date in URL before, so I had also added jekyll-redirect-from gem to gems section. With this gem installed, you can tell Jekyll to create redirects from defined URL to the current page or post. This is done with Front Matter instruction on top of the post. For example:
---
layout: post
title: Resurrection
redirect_from: "/resurrection/"
---
Note that the redirect_from value needs to have trailing slash, otherwise GitHub Pages will serve the generated document as file download instead of a regular page, causing browsers to download it. Hopefully, this will not cause SEO problems since my previous URLs were without the trailing slash.
GitHub itself can serve as an editor for your posts. Since there were only nine posts on my blog, it was not necessary to create some kind of migration tool. I just added them one by one through GitHub repository (they were already in Markdown format).
One thing that needed to be changed was the format of links. Markdown supports two types of links inline and reference. I had reference links in my posts. They were processed correctly on post pages, but post excerpts on home page did not process them - they were displayed in markdown syntax. After switching to inline links it worked correctly.
Domain redirection
My old blog was hosted on ASPnix under a custom subdomain. Following the GitHub guide, I had to delete the subdomain first and create a custom cname record for blog that points to miroslavpopovic.github.io.
Also, FeedBurner had to be redirected to use /feed.xml file instead of /feed. Users that were subscribed to my RSS feed will get one time refresh of all items, since post ids are different.
Disqus was used for my blog comments and since my post URLs are changed, I also needed to create the map between old and new URLs. There's a migrate tool in Admin area of Disqus for that. To get to Admin area, log in to Disqus, and select Admin from your profile drop-down menu on top right. Select your blog if not already selected and go to Discussion / Tools / Upload a URL map. You'll find the instructions on how to create CSV map file and upload it.
Final words
That's it. Migration was relatively straightforward with few problems here and there. My blog is now a Jekyll generated static site hosted on GitHub Pages.
GitHub repository for my blog is available here.
comments powered by Disqus