Converting the Blog to raw Jekyll

While I appreciated the ease of Octopress when getting started, I did fall out of the habit of writing. In the meantime Jekyll grew, from 0.xx to, in just a few years. And now the number one thing … supporting themes is not only native to Jekyll, but addressed via gems, keeping the blog itself pretty clean, and leaving layout and the other messy bits to the gem.

Tufte CSS

When I found the Tufte CSS themes for Jekyll I knew I’d found the right mix. I really liked the look of the clayh53 tufte-jekyll layouts. But it was out of date and not in line with the Jekyll 3.0+ gem-based themes.

Was I ready for pandoc? The tufte-pandoc-jekyll theme from jez would tell me, except that I found (1) the default CSS boring, (2) the included layouts were all the same, so therefore (3) there would be lots of localized theme overriding. I could combine the two, but what did that gain me?

Not sure I was up for building out templates, so as clean as the Tufte look is, I wanted something more turnkey. I found hydejack which had a nice looking theme and the free version included a lot of the niceties necessary for a blog, while the paid version offers many more features for later upgrade.

The Process

I took the easy way out, and basically started from scratch with Jekyll. I installed the latest version of the gem. I was a bit out of date:

$ gem list jekyll
jekyll (3.6.0, 3.5.2, 0.12.0)

So, there were a lot of upgrades to jekyll since I started using Octopress.

I decided to start from scratch, and not try to modify my existing blog repo. So renamed that source directory to octopress-blog. Following the Jekyll Getting Started guide I started a new blog:

$ jekyll new blog

$ tree blog

├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2017-11-01-welcome-to-jekyll.markdown

That is pretty clean. And such a nicer workflow than forking a GitHub repo and it’s associated themes, css, javascript and such.

The default theme for Jekyll is ‘minima’ and we get some basic configuration for free, including the use of that theme. Here is the relevant excerpt from config.yml

# Build settings
markdown: kramdown
theme: minima
  - jekyll-feed

I copied some of the standard configuration parameters, such as blog title, my twitter handle etc, and then started getting comfortable.

Getting comfortable

Before I started exploring potential themes, I used the minima theme to get familiar with Jekyll as a blogging tool. So the first thing I did was bring over my relevant config and content. Looking at the expected directory structure for Jekyll I brought over my octopress_blog/source/_posts to the root of my new blog cp -pr octopress_blog/source/_posts blog/_posts. Already we can see this is going to be easier to work with.

Running jekyll serve I could now see my old blog in the new platform with th e minima theme. This was perfect for getting comfortable with the differences and let me know what I was missing from octopress … for example no built in sidebar with recent posts. That would be something I’d miss, but maybe a new theme would have it.

I added a _drafts directory, and started writing this post subl _drafts/converting_to_raw_jekyll. Drafts was an upgrade to Jekyll that wasn’t available in the older version of Octopress I was using, and was one of the driving forces for my upgrade. I had to upgrade Octopress anyway, and it was apparently abandoned. This feature alone is worth the trouble.

I could see my new post (dated current date) with jekyll serve --drafts.

After exploring the static pages functionality I removed (for now) the page. After a bit more tweaking I have a directory that looks like this:

├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _drafts
├── _posts
├── _site


Now it was time to start exploring themes. This is where I realized that I wanted to keep to the Jekyll 3 gems, it became as easy as modifying my Gemfile and a line (or two) in _config.yml. I could compare themes with something as simple as git checkout <themebranch> and my base directory remained clean.


So, now that I’ve settled on the hydejack theme for my upgrade, and I’ve cleanly converted my content to a simple repo structure, it’s time to tweak the bits of the theme and then publish this post.

I think having a cleaner repo will help me be more inclined to blog.

Customizing hydejack

Most of this could be done via hydejack config settings:

accent_image: /hydejack/assets/img/sidebar-bg.jpg
accent_color: '#A85641'

There are plenty of other configuration options also. For multi-author blogs there is an entire configuration for defining unique author email, twitter handle etc.


I can’t even pretend that I have a better solution than Andy Croll’s Heroku deploy I’ll just list that here.

I was already on heroku, so I was familiar with the process. I needed to make a new heroku project, just because I didn’t want to break my 1’s of views per month while I was converting to a new repo source. And I needed my CNAME to propegate of course.