16 Sep 2018

Moving to Jekyll

So I’ve finally grown tired of beating my head against the WordPress wall. I am sick and tired of all of the routine overhead involved with WordPress. I get spastic every time I see another Russian/Chinese/Viagra spam comment bot, and I get a migrane every time mod_security shits a fit and blocks all of the back-end PHP. Fire erupts from my ears and obscenities from my mouth. The whole routine just sucks time away from actually doing work and generating content. Combine that with the increased attack surface and inherent difficulties with DR, it’s time to go. I want something that relatively simple, not much harder than actually writing the content, and doesn’t require me to learn an entirely new markdown langauge.

So I’ve finally grown tired of beating my head against the WordPress wall. I am sick and tired of all of the routine overhead involved with WordPress. I get spastic every time I see another Russian/Chinese/Viagra spam comment bot, and I get a migrane every time mod_security shits a fit and blocks all of the back-end PHP. Fire erupts from my ears and obscenities from my mouth. The whole routine just sucks time away from actually doing work and generating content. Combine that with the increased attack surface and inherent difficulties with DR, it’s time to go. I want something that relatively simple, not much harder than actually writing the content, and doesn’t require me to learn an entirely new markdown langauge.

Why Jekyll?

Jekyll makes sense for me. Operationally, I want a a low overhead to generating and publishing my content. I want to be able to maintain a backup copy of my site without having to setup a duplicate WordPress server. I’ve already become accustomed to writing in markdown since moving over to NextCloud and using the Markdown plugin. And I know my way around a command line.

I would not recommend Jekyll for everyone…or anyone not technically inclined. You need to install a Ruby dev environment, learn the syntax, and understand how it all works to produce a static site. If none of that makes sense to you, move to a hosted WordPress site where someone else does all of the crap work for you.

As a matter of fact, run over to Jordan Harbinger’s to listen to a podcast or two and support his show using a HostGator discount code! And if you want to hear random geek-induced fits of techno-rage, check out his producer’s show Grumpy Old Geeks. Boom - two shameless plugs in one paragraph. Seriously tho - both are great shows!

How do you do it? Well there’s plenty of good blog posts on that, so instead of re-inventing the wheel:

How I did it…

  • I didn’t bother moving my comments over to Discus. If you want to comment, use my twitter please.
  • Installed the prereqs, then installed Jekyll.
  • Created a new skeleton blog in a folder syncing with my NextCloud to facilitate use on multiple machines.
  • Installed Ben Balter WordPress Exporter for Jekyll on my existing site.
    • Make sure you have php-zip and php-gd installed or you will get a 500 error.
  • Rename _config.yml to _orig_config.yml so you can grab what you might need out of it.
  • Copy the exported files into your skeleton directory.
  • CD into the blog directory and run jekyll build
    • Extra points if you remember to actually CD into that new directory before you run the build/serve commands. I had a facepalm moment here.
  • Run jekyll server to see the site on http://127.0.0.1:4000.
  • Fixed any issues
  • Removed my WP site and published this one.

Poke around - you will definately need to fix a few things, like deleting the defaults that Jekyll drops in. You will also need to alter _config.yml to fit your site, social media links, etc. as the defaults are pretty bare.

Things to fix

  • Make sure to set the site’s title directive in the config file.
  • Delete the empty directories. Also delete anything from your wp-content/uploads directories related to any WAF plugins.
  • Fix any HTML entity issues by hand. I tried recode and it borked all of my posts up in good shape.

Left to do

  • I need to integrate the site deployments directly into my jekyll config…because lazy.
  • Decide if I want a different theme

Handy tidbits

Limiting the number of posts on the homepage.

I have a substaintial number of posts ported over from Wordpress and my Blogger sites, but I really only want the most recent posts on the home page. After spending a lot of time playing with paginator and not getting it working, I stumbled across a dead-simple option. First, copy home.html from the gem’s _layout folder into the _layout folder in your blog (create if it doesn’t exists). This will allow you to override the original file completely. Open home.html, then find the for post loop and add limit:3 and you should only have the 3 latest posts displayed. As a bonus, my build time dropped to a couple second.

    {% for post in posts limit:3 %}
	...
    {% endfor %}

If you do not know where to find the original files in the gem, issue this command:

bundle show <gemname>
Excerpts

Want to break long blog posts up so only a bit will show on the homepage, etc.? Setup a seperator tag in your _config.yml, then embed those into your blog posts. See the Jekyll Docs for more info.

excerpt_separator: <!--more-->
Themes

Here’s the most important tip for working with themes: MAKE A BACKUP BEFORE YOU DO! You could fork the code if you are using git, but I chose to just create a new skeleton blog using jekyll new and start from there.

If you are new to Jekyll, I’d advise sticking to gem-based themes to ease your confusion level. The default Minima theme is great, but lacking a few key features that I wanted such as pagination or limiting the # of posts of the home page. I started digging into Minima-Reboot after a few less than stellar attempts to customize Minima. There are a ton of great themes out there, but not many are gem-based for some reason.