I went down a 🐇 hole yesterday when I decided I wanted to try a new CSS framework. It started innocently enough, I found Siimple and figured I’d give it a try here. Siimple has SCSS files so I wanted to import them directly rather than used their minified distribution CSS. However, I got an error running Jekyll 2 when importing their SCSS. Though I filed an issue on their repo, I figured maybe it was a problem that would go away if I updated my Jekyll version. I used Chase’s handy gems-cli tool to grab the latest version of Jekyll to put in my Gemfile and, while I was at it, I updated nokogiri, kramdown, coderay, mini_magick, rake, and mechanize, too. I figure if you’re going to upgrade a gem, go big or go home, right?

After updating all my gems, I got a few deprecation warnings about how I was configuring Kramdown. I updated my configuration from this:

kramdown:
  use_coderay: true
  coderay:
    coderay_line_numbers: nil # nil|inline|list|table
    coderay_css: class # style|class

To this:

kramdown:
  enable_coderay: true
  syntax_highlighter_opts:
    line_numbers: table # inline|table
    css: class # style|class

I couldn’t seem to turn off line numbers entirely, but the original reason I’d done so was the numbers would copy when you tried to copy a block of code. Choosing the ‘table’ option fixes that problem, so I’m happy to leave line numbers turned on.

However, even with deprecation warnings fixed, I was getting a ‘stack level too deep’ error from Jekyll and it would fail without running the server. I tried disabling all my plugins; nope, still broken. I tried removing some plugins and replacing them with gems, such as using jekyll-archives for having tag and category archive pages. Nope, still broken. I added new gems that weren’t required with Jekyll 2, such as jekyll-paginate and jekyll-coffeescript; nope, still broken. I tried removing and updating some of my _config.yml flags… nope, still broken.

I decided to create a brand new Jekyll site and copy over 3till7.net’s content until the new site broke. However, I had a .ruby-version file in 3till7.net for some reason I can’t remember, and when I created a new Jekyll site, there was no .ruby-version. So the new site was using a later version of Ruby on my computer. It failed trying to install therubyracer, which was necessary because I use the jekyll-lunr-js-search gem.

I was getting an error about “dyld: lazy symbol binding failed: Symbol not found” which is certainly something I’ve seen before. Like every other time therubyracer has flipped out, I was able to fix it with a combination of uninstalling and reinstalling packages while passing in special flags to use system libraries. This was what eventually did it for me in El Capitan:

gem uninstall libv8
gem uninstall therubyracer
gem install libv8 -- --with-system-v8
gem install therubyracer -- --with-v8-dir=/usr/local/opt/v8-315
bundle config --local build.libv8 --with-cxx=/usr/local/bin/g++-4.2

After I got the new Jeyll site’s dependencies installed, I was able to run it with no problems. After copying over a few posts and the plugins they needed, I was able to reproduce the “stack level too deep” error. It turned out to be my jekyll-lightbox-tag configuration. The plugin has the following:

# Prevent Jekyll from erasing our generated files
site.config['keep_files'] << settings['output'] unless site.config['keep_files'].include?(settings['output'])

I modified it to puts settings['output'] and it was adding '.', which is just what I had told it to do in my _config.yml:

lightbox:
  output: .

My original goal with setting that directory for generated output was to have generated images put in the same place as their originals. However, as a quick fix to get around not being able to build my site at all, I removed the output option. Jekyll was giving me a different error now, which meant progress! Now the Lightbox plugin stores generated images in a generated/ directory, which I can live with.

I was getting an error about “Yikes! It looks like you don’t have pygments” though how syntax highlighting was ever working with my old Jekyll 2 site if Pygments wasn’t available is beyond me. I tried pip install Pygments but didn’t have pip. I fixed that with:

brew install python
pip install Pygments

However, once Pygments was installed, Jekyll still gave me the same error about not finding Pygments. What do you mean, I just installed it! I fixed this via gem install pygments.rb and then also adding gem 'pygments.rb', '~> 0.6.3' so I’d get the gem installed later if I tried to work on a different machine.

The next error preventing Jekyll from building successfully was my use of the Siimple SCSS files. I switched back to my old layout temporarily since it wasn’t using Siimple. Now my site was building and my syntax was highlighted!

The next problem was every time I would save a file and cause the site to rebuild, it wouldn’t actually complete because of an error with Jekyll::Converters::Markdown while converting my About page. So I’d have to Ctrl-C Jekyll and run it again, which would succeed. There’s nothing special in about.md, so I couldn’t see why that page was the problem. I banged about, trying different things like reducing the contents of about.md and disabling plugins again, but I couldn’t fix it. I thought maybe I could turn off auto-rebuilding, but I couldn’t seem to, even when I didn’t pass Jekyll the -w flag. What I ended up doing was dropping my Jekyll version back from 3.1.2 to 3.0.3. Now the whole site builds when you first start Jekyll as well as when you update a page.

By this point, the Siimple maintainers had responded to the issue I filed, saying there was a problem on their end but they had a fix for me. I used their updated SCSS files and Jekyll was happy with them. So I guess I needn’t have updated from Jekyll 2 at all, since going to Jekyll 3 didn’t help me use the original Siimple SCSS. I’m glad I got the site updated, though, since Jekyll 3 seems to be faster about rebuilding than Jekyll 2 was.

And that’s my long story of how I updated to Jekyll 3 to try and parse invalid SCSS but that didn’t work and instead introduced a whole slew of other issues to fix but then the bad SCSS got fixed and the upgrade issues got fixed so now 3till7.net is on Jekyll 3 and using Siimple’s SCSS so it all worked out after all. 👌