Passionate Development

Upgrading to Octopress 3 - Part 2

On the previous post, I’ve mentioned my frustrations with the old Octopress.

This site is now happily built by the new Octopress 3. And here is what I’ve done to upgrade it.

First of all, I generated a test site using the octopress generator. I will use this test site as a point of reference during the upgrade process:

  • gem install octopress
  • octopress new test-octopress

Then I went into my site directory and created a new git branch for this upgrade work.

Update Gemfile

Then I replaced my Gemfile with the following:

source "https://rubygems.org"

gem "jekyll", "~> 2.0"
gem "octopress", "~> 3.0"
gem "bourbon"
gem "pygments.rb"

group :jekyll_plugins do
    gem "octopress-date-format"
    gem "octopress-image-tag"
    gem "octopress-quote-tag"
end

# I don't use these atm - you might need them:
# gem "octopress-solarized"
# gem "octopress-gist"
# gem "octopress-video-tag"
# gem "octopress-codefence"
# gem "octopress-code

Run bundle install

Move directories

Next step is to move some directories - compare your directory structure to the one that you generated earlier. In my old octopress site, everything was under _source directory, so I promoted them to the root to be inline with the new octopress structure:

git move source/_includes/ _includes
git move source/_layouts/ _layouts
git move source/_posts/ _posts
git move source/_templates/ _templates
git move source/stylesheets/ css

Let’s try generating the site by running bundle exec jekyll build --trace.

Now this is the challenging part, I encountered few errors, below is how I fixed them - you might get different result.

Plugins directory no more

First of all, the errors that you get will most likely caused by your code reference to the old octopress plugins (look at your plugins directory). Octopress 3 uses Jekyll plugin mechanism (more on this), thus the old plugins directory is now obsolete. In the end, I just decided to remove plugins directory altogether.

First up, the error that I got is include_array error. 

  Liquid Exception: Unknown tag 'include_array' in blog/index.html

So include_array is an (old) octopress plugin that allows inclusion of multiple files. To fix this,

I just do string search for include_array, remove them when they are not relevant anymore or replace it with multiple jekyll’s include_relative, for example, offending code: 

{% if site.blog_index_asides.size %}
  {% include_array blog_index_asides %}
{% else %}
  {% include_array default_asides %}
{% endif %}

Now becomes: 

{% raw %}
{% include_relative "../../includes/asides/recent_posts.html" %}
{% include_relative "../../includes/asides/github.html" %}
{% endraw %}

This actually lead to further simplication on _config.yml, I removed asides array from it as I don’t really used them (eg: googleplus, pinboard asides etc). And delete the files from _includes/asides.

Code highlight

I choose not to use octopress-codeblock plugin and just use jekyll’s highlight. This means doing a word replace on codeblock,endcodeblock to highlight,endhighlight.

Don’t forget to specify highlighter on _config.yml like this: 

highlighter: pygments

SASS problem

The hardest issue for me is to fix SASS issue, as mentioned on the previous post, the SASS code on my site is no longer inline with current SASS specs.

I’ve spent lot of time, removing the offending lines, rebuild, rince and repeat. Then it hit me, I could just do away with the SASS altogether since I want to get a new theme anyway.

What I need is just a working compiled CSS from these SASS. Unfortunately I couldn’t get it from the production version of this site, since I accidentally deployed a broken CSS to it :(.

Thank God for Way Back Machine aka archive.org, I retrieved my old CSS from there, put it on css directory and then remove _sass directory.

No date on my posts

By now everything is looking good, but when I looked at my posts - the date is missing. Looks like this is an caused by the old date plugin, it needs to be replaced by octopress-date-format. So include the gem under jekyll_plugins (see my Gemfile above).

But we also need to tell Jekyll to include it on _config.yml: 

gems:
  - octopress-date-format
  - octopress-quote-tag

Then word replace *_formatted to *_html for example: page.updated_formatted now becomes page.updated_html.

Some articles that helped me a bit during the upgrade: