Migrating from Octopress 2.0 to Octopress 3.0
I have been planning to move my blog to a new server and I thought it would be a good opportunity to try to migrate to the latest version of Octopress. I have noticed the development ongoing on Octopress 3.0 for a long time, and after the write-up about it on the main Octopress site I have been looking for the right time to test it.
To be clear, Octopress 3.0 is not done yet, but it has come pretty far. I am not sure if you can call it in beta stage yet, but it is pretty stable and works well.
Using Octopress 3.0 is very different than Octopress 2.0, but it is much simpler. Gone is the requirement to clone the official repository, instead Octopress is now a collection of Jekyll plugins. Styling can be done with Jekyll themes or Octopress 3.0 themes. There isn’t much of Octopress 3.0 specific themes available yet, the only one I have found is the Genesis theme in the Octopress repository and that is still under development. For the migration I am sticking with the default theme and will look into using Octopress Ink to create my own later.
Using Octopress 3.0
Instead of the custom rake commands that was used by 2.0, Octopress now has a separate ‘octopress’ command which is used to create and manage posts, and to deploy the site. Compiling the site is done using standard ‘jekyll’ commands. Check the documentation here.
Installing
Installing Octopress 3.0 is as simple as installing the Jekyll gem and then add the Octopress gems as Jekyll plugins.
Set up gems
Install Bundler and create a Gemfile with the following:
source 'https://rubygems.org'
gem 'jekyll'
group :jekyll_plugins do
gem 'octopress', '~> 3.0'
end
Install gems with
bundle install
Create a new site
Create a new site with the command
octopress new <site>
This creates a folder with the scaffolding needed for your site. Remember to move the Gemfile to the generated site folder. This enables automatic use of gems added to bundle. If you don’t do this you have to add each gem to _config.yml to enable them.
You can test the new site with the command
jekyll serve
Migrating old posts
Copy posts from your old site to the _posts folder and images to the image folder. Basic installation of Octopress 3.0 does not have support of everything version 2.0 has, but there are plugins for almost everything. E.g. to use the image tag {% img %} just install the octopress-image-tag plugin. I recommend copying posts one-by-one to make it easier to catch which Octopress plugins you need. The output from jekyll build or jekyll serve will show when something is missing.
You find the full list of available Octopress plugins on the GitHub site.
This is the Gemfile I ended up with after migrating all posts:
source 'https://rubygems.org'
gem 'jekyll'
gem 'wdm', '>= 0.1.0' if Gem.win_platform?
group :jekyll_plugins do
gem 'octopress', '~> 3.0'
gem 'octopress-codeblock'
gem 'octopress-codefence'
gem 'octopress-solarized'
gem 'octopress-pullquote-tag'
gem 'octopress-image-tag'
gem 'octopress-render-code'
end
Styling and layout
The difference in styling and layout of your migrated post will, of course, depend on the theme you are using. I wanted to focus on getting the content and plugins in place first, so I selected to use the default Jekyll theme while migrating and only do minimal tweaks to the CSS layout when needed to make the posts look reasonable.
Code block styling
To get the same code styling as is default in Octopress 2.0, i.e. Solarized, use the octopress-solarized plugin. Remember to add {% css_asset_tag %} to the site layout if you are using a Jekyll based theme. In the default layout you add it to _layout/default.html.
Image layout
Default theme is pretty basic and does not contain much styling of images, so there is no support of the layout options for the {% img %} tag. I added basic layout support by copying from the Octopress 2.0 layout.
.basic-alignment {
&.left { float: left; margin-right: 1.5em; }
&.right { float: right; margin-left: 1.5em; }
&.center { display:block; margin: 0 auto 1.5em; }
&.left, &.right { margin-bottom: .8em; }
}
.flex-content { max-width: 100%; height: auto; }
img {
@extend .flex-content;
@extend .basic-alignment;
}
Pull-quotes
The pull-quote plugin does not ship with it’s own CSS styling so to make them show up it is necessary to add the styling classes to the theme. Inspired by this article I added the following to theme layout.
/*
* Pull quotes
*/
.pullquote-right:before {
/* Reset metrics. */
padding: 0;
border: none;
/* Content */
content: attr(data-pullquote);
/* Pull out to the right, modular scale based margins. */
float: right;
width: 320px;
margin: 12px 0px 24px 36px;
/* Baseline correction */
position: relative;
top: 5px;
/* Typography (30px line-height equals 25% incremental leading) */
font-size: 23px;
line-height: 30px;
}
.pullquote-left:before {
/* Reset metrics. */
padding: 0;
border: none;
/* Content */
content: attr(data-pullquote);
/* Pull out to the left, modular scale based margins. */
float: left;
width: 251px;
margin: 12px 31px 24px 0px;
/* Baseline correction */
position: relative;
top: 5px;
/* Typography (30px line-height equals 25% incremental leading) */
font-size: 23px;
line-height: 30px;
}
Deployment
Octopress 3.0 have built in deployment using git, s3, rsync and more. As I am hosting my site using nginx on my own server I use rsync to deploy.
Again, Octopress 3.0 makes it pretty simple to set it up, just use
octopress deploy init rsync
to create your deployment configuration _deploy.yml which you can edit to set specific configuration.
Rsync
If you deploy from Windows you need to install the rsync command yourself. I used cwRsync which has a free version based on cygwin. Simply download zip, extract and add to path. Modify cwrsync.cmd to match your environment.
Permissions
nginx is quite strict on file permissions on the host, and I found with help from this article that you need to set the permissions every time you deploy. Adding the following rsync flags to _deploy.yml fixed it.
OSX:
flags: -avz --chmod=Du=rwx,Dg=rx,Do=rx,Fu=rw,Fg=r,Fo=r
Windows:
flags: -avz -e "ssh -i /cygdrive/C/key/id_rsa" --chmod=Du=rwx,Dg=rx,Do=rx,Fu=rw,Fg=r,Fo=r
On Windows it is also necessary to add the full path to the SSH key, on OSX you can just add the key to your key chain.
Tips
Installing/updating Ruby on Windows
On Windows use yari.
To use Ruby 2.2.2 use the command yari 2.2.2 which will download Ruby and set-up the path.
Ruby 2.2.2 gems
Ruby 2.2.2 is fairly recent and not all pre-compiled gems supports it yet. Running jekyll serve may lead to exceptions like this
yari/ruby-2.2.2-i386-mingw32/lib/ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- hitimes/hitimes (LoadError)
If this happens you must remove the gem that causes the LoadError and re-install it using --platform ruby when installing.
gem uninstall hitimes
**Remove ALL versions**
gem install hitimes -v 1.2.2 --platform ruby
This will recompile the gem on your system.
Displaying liquid tags in posts
Displaying liquid tags like {% codeblock %} in posts like this can be hard as these tags are always interpreted by Jekyll. There is no short and easy way to escape them, especially in inline text. Some Googling showed that it it is possible with some esoteric use of {% raw %} to escape liquid tags inline, but it is really awkward. The simple solution is to use the Octopress plugin octopress-escape-code which automatically escapes code blocks and more. Just add the plugin to the Gemfile and add escape_code: true to the posts YAML front-matter.