Jekyll for WYSIWYG'ers

27 Jun 2014

Why Jekyll and this whole static sites business?

About a year ago, a sweet hosting deal I’d managed to finagle fell through and my modest personal website needed a place to live. I’d been using Wordpress for years and had become fairly familiar with its workflows and quirks. Between my personal writing and work-related writing, I’ve probably set up a dozen Wordpress sites over the years, but never really got past the official installer scripts, WYSIWYG editors and, occasionally, small php edits here and there.

I think Wordpress is great. My employer just switched over and our communications folk love it. There’s a lot of easy-to-access documentation and no matter where you’re working, there’s probably someone familiar enough to help you out of a jam. That being said, I never really had fun working with it. I like to tinker, take things apart and understand what’s going on when they break. Wordpress is just too complicated for my newbie skills and I didn’t feel I was able to get a firm enough grasp to really understand what was going on under the hood. Enter Jekyll.

The concept of static pages appeals to my tinkerer sensibility. Without all the php and complex database structures, I stand a fighting chance of comprehending what’s going on each time I commit a new post and if something breaks it’s not likely to affect the whole site, leaving me totally helpless to fix it. And it doesn’t hurt that pretty much all of the geo tech folk I admire are using it.

I really like writing Markdown, whether it’s for a blog post, conference notes or a presentation outline. Folks all over the web have extolled its virtues, but I’m particularly fond of this post by Ben Balter on why it’s about more than just semantics.

So…yay static pages. Yay markdown. Yay open source. Jekyll seemed great but I was still without hosting and sort of hesitant to plunk down some cash on what would ultimately be an experiment. Luckily, GitHub’s free GitHub Pages already run Jekyll and offer free hosting. To sweeten the deal, it’s fairly trivial to retain your existing URL.

I just want to point something out that sort of escaped me when I was looking into making the switch. You’ll see a lot about how GitHub pages are “powered by Jekyll,” but unless you’re already familiar with the way Jekyll works, it might not immediately be obvious what this means and you might miss one of the biggest benefits of buying into the Jekyll/GH Pages environment. “Powered by Jekyll” means that, rather than running your new Markdown posts through Jekyll locally then committing then resulting files, you can simply commit your posts and GH Pages will churn them through Jekyll for you. I initially assumed that in order to post to my blog, I’d have to be working on a computer with Jekyll installed so you can imagine my delight when I realized I could create, edit and commit posts from anywhere. Pretty neat stuff.

There are many thousands of words all over the web explaining how to set up Jekyll, so I’ll refrain from spelling out the whole process (see the resources section at the end for some helpful links) and instead just outline some of the barriers I encountered and how I overcame them.

Getting Jekyll running locally on OS X

Before you dive into the Jekyll hot tub, be sure you understand that you’ll need to do some work in the terminal and if you’re new to this type of thing, it’s probably going to get messy. But that’s okay! You (probably) won’t break anything beyond repair and you’ll learn a lot in the process. The official Jekyll docs are essential, but there are some other great guides out there as well.

Windows users are kind of out of luck in this department. It’s possible to get up and running, but requires some special steps that I won’t get into here. Once your site is built you can still post from a Windows computer, but you won’t be able to do all the fancy local-side Jekyll stuff.

I ran into all kinds of newbie problems getting Ruby working, but they pretty much all stemmed from my improper use of too many package installers and, when I got frustrated, sudo’ing myself into oblivion and ruining all of my file permissions. Don’t be like me. Follow the documentation and don’t abuse sudo.

Stuff you should install on your mac:

• The latest XCode command line tools
• RubyGems (comes with Ruby 1.9 and greater)
• Ruby Version Manager (RVM)
• Bundler
• Homebrew
• Jekyll!

Mavericks is a pain

I foolishly updated OS X right in the middle of trying to wrap my head around Jekyll and encountered all kinds of issues that are addressed in this article about configuring Mavericks. It covers some basic stuff like un-hiding your library folder, fixing your PATH (read the comments to get a broader view on PATH issues) and setting up Homebrew.

System Ruby

I had a lot of problems with Ruby, which all seemed to trace back to the pre-installed version of Ruby that comes with Mavericks. I’m no Ruby expert, but it’s much easier to work through Ruby Version Manager rather than deal with the many issues that come from working with pre-installed Ruby. Do yourself a favor and set up Bundler and RVM before diving into Jekyll.

Configuring a custom domain registered through GoDaddy

This step has actually gotten a bit more transparent in the months since I set my site up. This official GitHub help doc should actually provide all of the information you’ll need, but if you’re unfamiliar with GoDaddy’s DNS settings panel, this guide has a lot of helpful screenshots, though the author only sets up one A record. You’ll need the two listed in the previously mentioned official help doc.

TIP: You might run into some documentation that mentions setting up a gh-pages repo. This refers specifically to Project Pages. If you’re setting up a User Page, you should ignore references to gh-pages.

Understanding templates and theming

Reading through the Jekyll documentation, I felt like I had a fairly strong understanding of the mechanics behind Jekyll’s template system, but had a hard time making it work in practice. I really wanted to hand-code everything, but ended up settling on a simple pre-built template. One of my goals is to build my chops a bit and so far I think tweaking a simple existing template is the right choice. Jekyll is transparent enough that I can get a good sense for how everything works, save myself a lot of headache and easily make some deeper changes to the templates.

I am currently using Poole, which includes everything you need to get started poking around Jekyll. The author, Mark Otto, has done a great job laying out documentation and building clear examples. Joshua Lande has posted a really nice guide to working with Poole as well.

Resources

• “SEO” with site maps
  • I also didn’t quite understand how to add jekyll-sitemap to my _config.yml file. It should look like this:

    gems: ['jekyll_sitemap']
  

• Date parsing problems. I had to remove date_to_string from {{ post.date | date_to_string }} in my post.html template because it was passing a nil value. See this issue for more details.

  Bonus Tip! After fixing my date parsing problem and adding the above resource note, this post mysteriously broke again! The issue was that Jekyll interpreted the code blocks, which included my original broken code, as Liquid code rather than text. I found this post super helpful. In short, you’ll want to use the raw tag like so:

  {% raw %}
  some liquid stuff
  {% endraw %} 
  

• Creating an “Archive” page. See “Customizations” section.
• RSS feeds - a couple of options using templates to generate feed xml.
• OS X Configuration
• Keeping Jekyll Up to Date