January 06, 2014

A New Website, part 2

The Darker side of Jekyll (aka Hyde)

My website (and this website) runs on Jekyll. I love it and I have very few bad things to say about it. These are those bad things.

###Page vs Post

I don’t really know whether or not there’s a distinction between these two things. Every now and then I’ll have a problem where I think the solution is to change a variable from page.layout to post.layout or something but that doesn’t fix it.

###Categories

I have two categories on my site, work and basement. Making separate index pages for them was simple enough, what wasn’t was figuring out a way around Jekyll’s default previous/next behavior, because it provided no way to only cycle through posts of the same category. I ended up using this plugin, and modifying it a little bit. The original makes separate previous and next links for each category, but since I only have two categories and a post will never be in two categories at once, I re-wrote some of it to make only two links, which are essentially next_in_category and previous_in_category.

###Limitations of Liquid Templating

Liquid doesn’t really have parent/child templates, which is a shame. You can sort of acheive the same thing with multiple nested layouts, but layouts can only nest inside of each other, and not override each other in specific places like parent/child templates can usually do with block or something equivalent.

In my case, getting custom CSS and JS onto pages that use the same layout was a nightmare. The default layout will look like this (in pseudo html/liquid):

<head></head>
<body>
    {{ content }}
    <footer>...</footer>
</body>

Because all the content is in that place, anything specific to that page can’t go anywhere else. Meaning that if I want to put custom CSS in the head, or custom JS at the end of the body, I’ll have to do a workaround and put it in the YAML. Which sucks. It’s what I’m doing though.

###Markdown

This is more of a limitation of markdown than Jekyll itself, but I thought it belonged here. I have a few gripes:

  1. Images aren’t considered block level elements, so markdown automatically wraps them in <p> tags unless you write explicit markup yourself and wrap it in a <div> or something. I use <figure>s as wrappers because it’s more semantic.

  2. There’s a weird bug with Jekyll’s markdown parser that makes your first paragraph disappear if it has a colon(:) inside it.

  3. You have to write inline html if you want to add classes to things. Which isn’t so bad but I do this pretty regularly.

  4. I had a lot of trouble writing this post because you can’t just write inline code without escaping it like <this>. Also, escaping liquid tags is a pain.

Honestly though, Jekyll is great and I’d recommend it to anyone. It’s flexible without a ton of coding, really quick to set up, easily deployable, and doesn’t get in your way. Most of the time.

— @RobertVinluan