Wa-hey there! Your old pal Monty is here with a radical new Jekyll review! Jekyll’s a blog framework that’s been making waves lately as a result of being used on this blog. A few things jumped out at me during my Jekyll Journey that I thought I’d write about. Let’s get started!

A picture from my recent vacation. Jealous? A picture from my recent vacation. Jealous?

Documentation

I’m just going to say it: the Jekyll docs are terrible. I started using Jekyll without any knowledge of things like Liquid or SCSS or Markdown. The docs don’t explain what these technologies are or how to use them. The Front Matter page doesn’t even mention what front matter is.

Throughout setting up my blog I was trying to consult the Jekyll docs and repeatedly hitting my head against the fact that they are useless. Much of it reads like a simple (and incomplete) reference, devoid of informative content. I had more luck figuring out how to do things from random blog posts on the Internet.

Have fun finding something in the docs with the laughable organization of the site. It would be immensely helpful to have simple search functionality; instead, the docs are a scavenger hunt of biblical proportions. Big thumbs down from me on this point.

Categories

Where are they?! Where are the categories?! If you don’t know what I mean, at the bottom of every one of my posts you’ll find something like this:

Alt text, baby.

All other blog frameworks have this by default so you’d better believe it’s important. Not Jekyll, though! I had to implement this myself.

The docs only mention (indirectly) the site.categories variable but don’t explain how to use it, or that it’s actually an array. (I know we talked about this, but the docs are terrible.) I had to reference three different blogs just to find out how to create an index of categories (see my site’s implementation here). This is Blog Frameworks 101, guys.

For anyone else struggling with this, I may write a blog post explaining how to do all this for your own little blog. It’s not difficult at all, once you know what to do.

Gem-Based Themes

In Jekyll 3.2, new projects are initialized using something called gem-based themes. All you need to know is that these themes are installed using RubyGems and that the theme files are hidden away somewhere on your computer. You can find them with bundle show <theme-name> on the command line, which will display the location of the gem’s folder.

The only quote-on-quote ‘advantage’ of gem-based themes is that your blog directory is a little less cluttered. However, I think that hiding complexity here is misleading, makes it harder to modify the theme, and is aimed at the wrong audience. Most Jekyll users are self-styled ‘hackers’1 and will be wanting to change the theme to suit their needs. Fortunately, you can copy over all the theme’s files from the gem directory to your blog directory to effectively turn it into a traditional theme. Having done this, you should only edit the theme files in your blog’s directory from here on out2.

Monty’s opinion is that Jekyll could have done without this feature.

Theme Quality

I was surprised to find that the default theme, Minima, is actually pretty damn good3. Sure, I still messed with it a whole lot, but it looks great out of the box and includes nothing unnecessary.

To find quality issues with Minima, such as standards noncompliance, I scanned my website using SortSite. I nearly had a heart attack when I saw the result.

The SortSite Surprise The SortSite Surprise

I composed myself and began to investigate. Although it said that montyflatts.com was “worse than average”, it didn’t find any real issues with the site. For example, the suggestion to have a ‘Sitemap’ link sounds strange to me and having checked a few popular sites, none of them had one. It seems like a ploy to sell their sitemap generator product.

SortSite did point out a few minor issues, but they are hardly worth mentioning45. For example, they say to include a link back to ‘Home’ on every page – good advice, but not all that important. I would recommend not to use SortSite and to use html-proofer instead. Here’s how it currently appears in my test pipeline:

bundle exec htmlproofer --check-html --internal-domain "montyflatts.com","www.montyflatts.com" ./_site

A final note about this theme: the content of posts is not justified for some odd reason. An easy fix in _layout.scss:

.post-content {
    margin-bottom: $spacing-unit;
    text-align: justify; // add this line
    ...
}

And you’ll probably want to put

text-align: left;

under h2 and h3.

Markdown

Markdown, and Jekyll’s variant kramdown, is alright for simple formatting of posts but is quite limited in what it can do. For example, you can’t center images or add captions without some hacking. I can’t help but think the developers of Markdown designed it during a drunken stupor. How can anyone have a blog without centered images?

Jekyll is nice because you can extend kramdown or change it out for another Markdown variant or just not use Markdown at all. I guess this is more a gripe I have with Markdown itself.

Verdict

So those are some of my thoughts about Jekyll. Would I recommend it?

Hell yeah, I would6!

That’s it for this blog post, check back next time for my DIY Categories tutorial. Catch you later! Hyah!

Later, suckers.

Footnotes

  1. Please stop overusing the word ‘hacker’. 

  2. Technically, you only need to copy over the theme files that you want to make changes to, as any file in your blog directory will override identically named files in the theme directory. However, this can get needlessly confusing and it quickly becomes burdensome to keep track of what you copied over. You’d also be working with an additional directory. Just copy everything over wholesale. 

  3. I didn’t try any other themes so I can’t comment on them. I like Minima, and it being the default means that I’ll be the only one using it. 

  4. It false-flagged a lot of non-issues as well. For instance, SortSite suggests always having underlines under links for the benefit of color-blind users. The thing is, browsers already have accessibility settings for such users, including the ability to override the appearance of all links. And underlines under links are ugly. 

  5. A lot of SortSite’s feedback was already written up as issues on Minima’s Github. Unfortunately, it looks like the issues are not getting fixed. 

  6. I like how configurable Jekyll is and how well-organized it is. I like all the different technologies it brings together, including Liquid, SCSS, YAML, and more. I like how lightweight and performant the resulting site is. All of this makes it a powerful framework, and dangerously high-tech.