January 09, 2017
I made this blog with Jekyll, and have been pretty content with the Jekyll experience, despite making the website while on a Windows PC (Jekyll doesn’t officially support Windows). Jekyll is a parsing engine that handles blogging logic for you, and makes it possible to host a blog on a static site. Removes the hassle of storing posts in a database, etc. Anyhow I just wanted to list a few gotchas to Jekyll in this post - even though Jekyll is pretty great, there are a few things that are just useful to keep in mind to save you some time.
1. Setting up Jekyll on Windows
As mentioned, Jekyll doesn’t officially support Windows. You can get it to work on Windows with a few tweaks anyways though. The official Jekyll documentation does a good job of explaining what you need to do, but I remember installation being a bit fussy for me. Here’s a quick Cole’s Notes style set of instructions for what I did to get it working on my Windows 10 PC eventually:
1) Install Chocolatey.
2) Install Ruby v2.2.4 by running the command choco install ruby -version 2.2.4. If you have a later version of Ruby installed, you MUST uninstall it before you do this. Simply setting the flag to --allow downgrade is not enough.
3) Install the corresponding Ruby development kit with the choco install ruby2.devkit command.
4) Navigate to C:\tools\DevKit2 in the command prompt.
5) Run ruby dk.rb init.
6) This will have created a config.yml file in the DevKit2 folder. Open this file and edit it to include - C:/tools/ruby22. For example, this is what my config.yml file looks like:
# This configuration file contains the absolute path locations of all
# installed Rubies to be enhanced to work with the DevKit. This config
# file is generated by the 'ruby dk.rb init' step and may be modified
# before running the 'ruby dk.rb install' step. To include any installed
# Rubies that were not automagically discovered, simply add a line below
# the triple hyphens with the absolute path to the Ruby root directory.
#
# Example:
#
# ---
# - C:/ruby19trunk
# - C:/ruby192dev
#
---
- C:/tools/ruby227) Run ruby dk.rb install in command prompt.
8) Install Jekyll with gem install jekyll.
This should be enough to run Jekyll to preview your sites on your local machine.
2. Watch out for paths
I’m used to setting paths in the head of my HTML like this:
<head>
<link href="/css/main.css" rel="stylesheet">
</head> This was working all fine and dandy for me when converting my site to Jekyll, until I created posts and none of the CSS would work on them. All of the other pages loaded the CSS just fine, so I sat there scratching my head for a while, looking in the wrong places to fix the bug. The js files and the navigation bar links weren’t working either I eventually noticed, so I was universally doing paths wrong.
Basically Jekyll runs into problems finding these resources when you go one level deeper - that is, whenever you are within a post. You must therefore dynamically prepend the first part of a path, since the directories change. Something like this is what I do:
<head>
<link href="{{ "/css/main.css" | prepend: site.url }}" rel="stylesheet">
</head> 3. Make sure you don’t date your posts in the future
Make sure none of the dates in your YAML front matter are set to the future, or Jekyll won’t build these posts. For example:
---
layout: post
title: "Jekyll Gotchas"
date: 2017-02-09
image: post-sample-image.jpg
---This is wrong, and Jekyll wouldn’t build it earlier today when I was previewing this site on my local machine, which gave me quite the scare. I had just edited the “date” value from another post I had copied and pasted in here, and forgot to change the month and day after changing the year.
There is an option you can set so that Jekyll builds these future tense posts, if you really want to write future tense posts for some reason. I didn’t really notice my date mistake and thought something went terribly wrong with the build for a few, panicked minutes.
Anyhow I don’t mean to hate on Jekyll at all. It is bundled as a Ruby gem, and even though I am no Ruby master I managed to mostly set up my site with Jekyll within a day. That aside, I like how Ruby has “gems”, haha. It reminds me of mining in Harvest Moon:
I remember reading somewhere in the Jekyll documentation a snippet wherein the writer seemed to really grieve the use of Liquid templating in Jekyll. They called it something like Jekyll’s biggest drawback, and lamented that Jekyll must use it for security reasons. I quite like Liquid templating so far, on the contrary. I think it makes code look nice n’ sleek, and didn’t have too much trouble picking it up. Maybe I just haven’t tried to do too many things with it yet though, haha.
Anyways, I’ll update this post the more I use Jekyll. These are just some things that gave me some head scratchin’ at first.