As you can see, we’ve moved to a brand new blog, powered by Jekyll. This is a good opportunity to shed some light on a process that, although not terrifying, is not totally without surprises.



In software in particular, there are no happy surprises. 



Switching

When we started 8th color, we set up this blog quickly as a way for us to write about our company and what we were doing. Since we started PullReview a year ago, it has become strongly oriented towards Ruby code and sustainable code.

The first version was in WordPress (self-hosted as we wanted freedom in the plugin selection) and it did the job for almost three years (first post in May 2011). What led us to look for an alternative was that when you wanted to do something outside WordPress’s impressive interface, it quickly became very complicated and time consuming, as well as being essentially a series of clicks to be done in the right order. Things as simple as setting up a small banner were taking us a lot of time as they required digging into WordPress.

The switch to Jekyll is natural for us: we are Ruby developers and familiar with markdown (thanks notably to GitHub issues and wiki pages). Middleman was an option but for a blog and not a generic website. Jekyll gives much more out of the box. 



At the time of migration, we had 150+ posts and 300+ images already in WordPress, so rewriting was not an option, and we had to keep manual intervention to a minimum. 



Let’s go through it in order: 



  1. Install Jekyll
  2. Migrate posts
  3. Migrate images
  4. Apply magic
  5. Migrate comments
  6. Tweak Jekyll

1. Install and run jekyll

An easy first step, just to get in shape. Jekyll can be installed, setup and started in four simple moves: 



gem install jekyll
jekyll new blog
cd blog
jekyll serve

Go to http://localhost:4000 and voilà, you have a blog!

2. Migrate posts

Now we need to fill it in a bit. Let’s export our posts from WordPress. WordPress has an option to generate an xml file with your whole blog content:

Settings > Export

Keep the default to export all, and save the xml file locally.

Keep the default to export all and save the xml file locally. 

You can then use jekyll import to retrieve all your posts. First you first need to install jekyll-import as it is not part of jekyll main gem: 



 gem install jekyll-import

You can then use jekyll import. There are several options here. Here is the command that worked best for me:

ruby -rubygems -e 'require "jekyll-import"; JekyllImport::Importers::WordpressDotCom.run({ "source" => "/home/martin/8thcolor.wordpress.2014-04-25.xml" })'

Note that despite the name, the JekyllImport::Importers::WordpressDotCom importer works great for self-hosted WordPress sites such as ours. 



From there, you should find all your posts in the _posts folder. Note that the importer does not convert your posts to markdown - Jekyll can handle the HTML without problem - but you’ll find a header added to each of your posts.

Let’s run jekyll again: My new blog!

3. Migrate images

One of the problems I saw directly after the migration was the images. I did not want to keep url links to the WordPress site so I had to get them into the new structure. After a little unsuccessful research on how to do it (the xml file normally contains everything, even the images), I went back to a simple solution. I downloaded the images from the WordPress server via FTP, keeping the whole directory structure “as is” (WordPress saves the images in a structure by year and then month).

I then copied this structure in a /images folder in my Jekyll project.

As I kept the structure, fixing the URLs was a simple replace from the previous blog url to the `` variable, for a result like:

  • Before: http://blog.8thcolor.com/images/2011/07/Business_Model_Canvas-1024x682.png
  • After: {{ site.baseurl }}/images/2011/07/Business_Model_Canvas-1024x682.png

4. Apply magic

While we had some criticism with regard to WordPress, the default look and feel of Jekyll is not really any better. Time to apply some magic! As Jekyll is using HTML/CSS, fixing the look and feel is very simple:

Apply Magic!

Well, it is simple as long as you are a web designer, or working with one (like we do).

5. Migrate comments

So, we have posts, a good look, and even images. What are we missing? Comments of course. We were using Wordpress default comments and as Jekyll did not provide its own comment system the easiest way we found was to migrate to Disqus.

As Disqus itself holds the comments, this was a part of the migration we could do before migrating the rest of the blog, by switching within WordPress to Disqus.

So:

  • Create an account on disqus.com
  • Add the “Disqus Comment System plugin” to your WordPress blog
  • Go to http://import.disqus.com/ and upload the xml file (again)

This will recreate your comments on Disqus, which will be very useful a bit later. Note that you can retrieve the comments you made using Disqus, so that they are correctly assigned to you.

6. Tweak Jekyll

We have posts, images and a comment system. This starts to look like a blog. Some tweaks to Jekyll can help:

By default, Jekyll uses the year, month and day as a link, while WordPress uses just the year and month. We wanted to preserve our links, in order not to break any external ones and also to allow Disqus to work. This can be fixed by modifying the permalink line in config.yml:

permalink:    /:year/:month/:title/

Add Disqus info

As we want the comments, we need to add a Disqus snippet at the bottom of our post layout page:

<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
    var disqus_shortname = 'myblog'; // your forum shortname

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); 
        dsq.type = 'text/javascript'; 
        dsq.async = true;
        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
    (document.getElementsByTagName('head')[0] 
      || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>

<noscript>Please enable JavaScript to view the 
<a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a>
</noscript>

<a href="http://disqus.com" class="dsq-brlink">comments powered by 
<span class="logo-disqus">Disqus</span></a>

Glitches

Finally, two little glitches I found:

Code highlighting

pygments works fine, but the transition from WordPress was not smart enough to migrate the system we used. As the code is still in pre and code tags, it was still easy to have them in fixed fonts, but enabling pygments correctly would require to pass on each snippet.

Zementa captions

The Zementa plugin allows easy searching and inclusion of images in your post. It also generates captions that were not handled very well by the migration. 



References

Credit where credit is due

This migration would not have been possible without following in the footsteps of earlier pioneers: 



Our thanks to them! 


And Jekyll’s doc has been useful too:

We still have to deploy this properly using GitHub, and get back our writing workflow, but that’s enough for today. Watch this space!