I have been using Octopress for blogging since 2013. Octopress is essentially a framework built on top of Jekyll, which offers vast convenient at the time, such as nice themes, automating in publishing to github, etc. I considered Jekyll a bit bare-bone and heavy back then. However, the ever-promised Octopress 3.0 is never coming officially, nor there is a friendly migration guide. The octopress github repo has stalled since 2015. Each time I wrote a blog post, there’s always some plugin or things break as I am using ancient age gems. It’s a time for a change. My new site is hosted at here.

After doing some study, I’ve decided to migrate my blog to Jekyll, because:

  1. Octopress is built on top of jekyll anyways. The migration is supposed to be a lot easier. Moreover, my blogging flow can more or less be preserved.
  2. I’ve originally thought of migrating to a framework written in Python, which I am more familiar with. However, I didn’t really find a better choice (please let me know otherwise in the comments).
  3. Jekyll has been actively maintained and has been integrated well with a lot of things, especially github pages, the host that I’ve been using so far.

The Migration

Since migration from octopress is not officially supported by jekyll, I spent some time working around the migration. Rough steps I’ve taken:

state of the art of my old octopress plugins

  1. Create a jekyll site following the instructions.
  2. Configure custom domain.
  3. Install themes. I used so-simple.
  4. Build and fix the errors. Most of them come from the plugins I had. For backward compatibility, I deprecated them gradually until my build passes. I am sure there are still some of them are causing error. But who cares for now 🙂
  5. Configure the theme. This took the most time. A lot of new things to learn and include.
  6. Use plugins such as jekyll-compose to help the publishing flow, e.g., create a new post and automatically open up my editor.

There are a few things that I didn’t solve quite nicely and on-going:

  1. I attempted to migrate my old theme foxslide. But it’s way too time consuming to do it. I ended up just using the jekyll gem theme, which is nice as I don’t have to copy-paste the source to my own repo.
  2. However, the so-simple theme itself poses some problem for me. The latest version as of writing is v3.2.0, which is released on Nov 5, 2019. There seems to be quite some new development going on and some nice improvements such as MathJax v3. Without a new release it seems no easy way to install with a breeze (as a gem).
  3. I used to use “$” for MathJax’s inline math. However, I realized there are a lot of time I did need to use the dollar sign for what it’s for. I’ve decided to go back to use the recommended \( ... \) for inline math. But seems not working (rendering) properly. Even in the demo page of so-simple theme.
  4. Separate the source and static files to a private and a public repo. I don’t like my markdown source to be easily copied in a public repo. I’ve always using a bitbucket repo to host the source privately (github did not offer free hosting at the time), and publish the generated sites to github. Octopress comes with some rake utils to handle the deploy and it handles it quite well. However, apparently I need to migrate that as well if I wish to continue to do that. Jekyll website offers some advices on automating the deployment process:
    1. Apparently, GitHub actions are easiest and well-supported one. However, it has to publish to the same repo which means both source and site will be public.
    2. Travis CI. This is a relatively “heavy” solution but it does work as what I wanted. With the help of this article, I was able to set up a Travis CI workflow to do. However, it does come with a cost: at the time of writing, the free plan only comes with 10,000 credits, and each time I deploy it will bill to it for the VM time usage. This means some time in the future, this will stop working for me. Meanwhile, CircleCI is offering 2500 free credits/week. I should probably explore this one.
    3. Use Github pipelines. This articles introduces how to do it.

mathjax is not rendering in so-simple’s demo page. lol


At the end, I was able to migrate my blog with the most part. There are still some weird or unexpected issues I need to address (e.g., images layout). I am definitely glad that this is doable within a relatively short time.