I have been using Octopress since 2012, and it works fine for me in all these years. But unfortunately the project has been abandoned since January 2015, which means it depends on a lot of legacy packages, and misses a lot of fancy new features. For example, the version I was using depends on jekyll-0.11.2, while jekyll-4.0.0 was already released in August 2019.

Although I don’t bother using the legacy software and was satisfied with the feature set as long as it’s working, setting up a new environment for the legacy software becomes harder and harder. On macOS, I need to use rbenv to compile and install a specific Ruby version for Octopress: Ruby at 1.9.3-p392. As the version is very old, when using Apple’s latest compiler (Apple clang version 11.0.0) or other GCC versions which are available on HomeBrew (I have tried GCC-4.9 and GCC-9), there are warnings during compilation (see this GitHub issue for an example warning), which ensures a failed installation.

$ rbenv install 1.9.3-p392
Downloading yaml-0.1.4.tar.gz...
-> http://dqw8nmjcqpjn7.cloudfront.net/36c852831d02cf90508c29852361d01b
Installing yaml-0.1.4...
Installed yaml-0.1.4 to /usr/local/opt/rbenv/versions/1.9.3-p392

Downloading ruby-1.9.3-p392.tar.gz...
-> http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p392.tar.gz
Installing ruby-1.9.3-p392...

BUILD FAILED

Inspect or clean up the working tree at /var/folders/mx/mfxgb8450d97ssnd588_bg980000gn/T/ruby-build.20130222110749.98264
Results logged to /var/folders/mx/mfxgb8450d97ssnd588_bg980000gn/T/ruby-build.20130222110749.98264.log

Last 10 log lines:
compiling safe.c
compiling signal.c
compiling sprintf.c
compiling st.c
st.c:520:35: error: implicit conversion loses integer precision: 'st_index_t' (aka 'unsigned long') to 'int' [-Werror,-Wshorten-64-to-32]
            i = table->num_entries++;
              ~ ~~~~~~~~~~~~~~~~~~^~
1 error generated.
make: *** [st.o] Error 1
make: *** Waiting for unfinished jobs....

It’s for sure that I can dive into the issue and solve it for now¹, but it also means that I have to go through the fix again and again to setup new environments. Besides, Octopress 2.0 is just a bunch of Ruby plugins and a beautiful theme on top of Jekyll, which is hard to understand ², maintain and upgrade ³. With a such layer in the middle, I feel frustrated when I want to change my blog’s behaviors, but find out that I couldn’t figure out how to do it.

With these obstacles on my way forward, I decided migrating away from the legacy blog system. There are two ways in front of me:

• Build a static blog generator from ground up with minimum features I need for my blog, most likely in Python, as learning Ruby before writing the project is too much fun for a weekend project.
• Migrate to the latest version of Jekyll.

No matter which way to way, I need to trim the current code base to figure out what’s the minimum feature set I need for my blog. In my old blogs, I mainly use the following Plugins from Octopress:

• Code Block. { % codeblock %} code snippet { % endcodeblock %}
• Include Code. { % include_code [title] [lang:language] path/to/file %}
• Gist Tag. { % gist 4321346 %}
• Block Quote. { % blockquote [author[, source]] [link] [source_link_title] %} Quote string { % endblockquote %}
• Image Tag. { % img [class names] /path/to/image [width] [height] [title text [alt text]] %}

For the first two usages, it’s straight-forward to replace them with triple backticks ```. For Gist tag, replace them with the GitHub embedded script. For quote block, switch to the standard markdown syntax: > at the beginning of the paragraphs I want to quote.

For image tag, I mainly use the tag to set a width or height to prevent an image becomes too large, which can be achieved with the following syntax support from kramdown.

![smiley](smiley.png){:height="36px" width="36px"}

After all these changes, my blogs finally don’t contain any Octopress specific syntaxes.

In the process of replacing all these usages, I began getting familiar with how Octopress works on top of Jekyll, and realized that it’s just a bunch of Ruby plugins, so it’s possible to migrate to Jekyll, while keeping the current theme and layouts with small updates to the current html templates. Although I am not married to the theme, I did spend a lot of time tweaking the CSS to make it look right.

Several hours later

After several hours tweaking, I have successfully migrated my blog to Jekyll 4.0.0, and it’s blazing fast now! With Octopress, it often takes more than 10 seconds to generate, while now, it only take less than 2 seconds. Besides, I am familiar with all the templates now and feel empowered to make any change.

Yo Ho!🍺

PS: As I have a very unique setting for my blog (no comments, no sharing, made a lot of changes to the Octopress default theme), I am not sure whether or not the way I migrate will be useful for others. Please send me an email if you are interested to check it, and I can share it with you.