Leaving Jekyll behind

Update 23/01/2023: After about 6 years of leaving this project as-is (I haven't been very active updating the site 😂), I finally wanted to get the finger out and make the site automatically build and release whenever I pushed a commit, so I put on my big-boy pants and spent the weekend updating all the dependencies, removing those that were no longer necessary, and generally turning it into a project that can be run via CI/CD. See the section at the end for details.

A while ago, I posted on how I was moving away from Drupal towards Jekyll, thus changing from a dynamic site to a static one. Well, over Christmas, I upgraded my 8 year old laptop for a spanking new Dell XPS 13 (which is great btw) and in the process of reinstalling all my programs, getting my different dev environments set up, and generally keeping my computer as fluff-free as possible, I took a good look at what was actually necessary.

Jekyll uses both Ruby and Python. I had originally installed Ruby a long time ago to test some Ruby on Rails stuff, back when it was the hot stuff, so it influenced my decision to install Jekyll in the first place. For my new laptop, I didn't want to install both languages just to generate my site, and firing up my old laptop just to do a build seemed like a pain (once you go SSD, you never go back), so something new was in order.

Enter heckle

I do do Node.js development though, and in searching around for a Node.js Jekyll replacement, I came across heckle, by marijnh. It seemed pretty straight-forward and did everything I was looking for, with the exception that it uses Mold as a template language instead of Liquid. Hmmm...

Enter liquid-node

Hunting around some more, I came across liquid-node (changed to liquid), by sirlantis. Liquid-node is a port of the Liquid template engine to Node.js, using Promises for all the asyncy stuff. Two points stood out on the features panel: "Based on original Ruby code" and "High test coverage". Seems like it would do the job just nicely.

JekyllJS

I started a project (TypeScript), based off of heckle, using liquid-node, and named it JekyllJS, the idea being that you could take your existing Jekyll site, run it through JekyllJS, and it'd produce the same content.

All in all, development went surpisingly smoothly. I found another Node.js module, js-yaml to handle reading the _config.yml and each post's frontMatter, and with heckle's code as a reference, I was able to get something up and running pretty quickly.

Until I hit an Unknown tag: "{% highlight %}" Exception anyway. I guess Liquid has been updated since the Node.js port happened.

Highlighting code

I have a lot of code samples across my site, and you can set up Jekyll to use Pygments or Rouge to handle this for you. I didn't find a Node.js equivalent, so I settled for highlight.js, which happily allows itself to be installed as a Node.js module to allow for server-side pre-rendering (as opposed to each client highlighting the code on each page load).

Liquid-node allows you to write your own custom tags, so I wrote one for the {% highlight %} tag that takes the chunk of text, and pipes it through highlight.js. The results are obviously different from what Pygments or Rouge generate, but I can live with the difference - as an added bonus, the CSS is smaller.

Other differences

It looks like this has been fixed, though as I changed how I was doing things, it was no longer an issue though. I did have to rewrite {% include_if_exists %} tag though, which I used to automatically include files and comments for posts when the relevant include exists. In any case, as liquid is no longer actively maintained, you're probably better off moving to liquidjs, but I didn't have the heart to changing rendering engines after getting everything working again 😅. The update to the {% include %} tag does mean that you need to drop the filetype from your includes. So {% include footer.html %} becomes {% include footer %}

When I added Markdown support using the marked node.js library I found that it was escaping all quotes for all reasons, including normal text ("don't", "can't", "I'm", etc). I don't particularly like this behaviour (it's still valid HTML though), so I added a fix around it. Just replace the marked.js file - included at the end of the post - in the node_modules/marked/lib/ folder if you want to do the same.

Another difference is the way that dates are parsed. Normally in your frontMatter, you'd specify a date like so:

date: 2016-01-23 19:50:00 +0100

and Jekyll would treat this date as-is, i.e. +1hr after GMT. JavaScript however, takes into account Romance Daylight Time, which handles the extra hour for daylights time. This means that if you're in the EU and you use CET during the winter, you'll use CEST during the summer, or during the last Sunday of March to the last Sunday of October, and +0100 will act as +0200.

var d1 = new Date( "2016-03-01 00:00:00 +0100" ) // Tue Mar 01 2016 00:00:00 GMT+0100 (Romance Standard Time)
var d2 = new Date( "2016-04-01 00:00:00 +0100" ) // Fri Apr 01 2016 01:00:00 GMT+0200 (Romance Daylight Time)

Depending on when you've published your post (i.e. the date), this behaviour can change the rendered day, or even month, which may or may not be a problem for you. I've not found a way around this behaviour, but if it's affecting you, you can try changing the date set in your frontMatter.

As for categories, I don't use them in my site, so I've no idea how they're supposed to render, so I didn't include them in JekyllJS.

The final thing I came across was when using {% if %} checks. I was checking to see if a variable was set in one of my templates using {% if someVar == null %}. For liquid-node, I had to change this to {% if someVar == undefined %} or simply {% if someVar %}.

The JekyllJS config

JekyllJS comes with a simple config file, config/default.json, meaning you can change a few things without having to re-compile the project. It looks like this:

{
	"src":{
		"404":"/404/"
	},
	"meta":{
		"keywords":"default,keywords,here",
		"description":"default description"
	},
	"opengraph":{
		"fb:admins":"XXXXX",
		"og:type":"article",
		"og:image":"/img/open_graph.png"
	},
	"highlight":{
		"parentClassName":"highlight",
		"shouldWrap":true
	},
	"server":{
		"port":4000
	}
}

which translates as

• src.404: the path for the file to serve as the 404 page, if you have one
• meta.keywords: the default meta keywords to add to each page if the page doesn't specify any. Set to null or leave out to ignore this
• meta.description: the default meta description to add to each page if the page doesn't specify one. If null or left out, then the description in _config.yml will be used (if set)
• opengraph.fb:admins: the ID of the Facebook user that you want to associate as the admin of the page. If null, then it's not added to the page
• opengraph.og:type: the default type for each page, unless overwritten. If null and not overwritten, then it's not added to the page
• opengraph.og:image: the image to use as the default OpenGraph share. If null and not overwritten, then it's not added to the page
• highlight.parentClassname: the classname for the parent node for highlighted code. Use highlight to keep with the Jekyll generated code, or hljs to use the highlight.js version
• highlight.shouldWrap: Should we wrap our generated code in a div? Use true to keep with the Jekyll generated code, or false to use the highlight.js version (in which case the highlight.parentClassname will be applied to the code tag
• server.port: the port to use when serving the site

Create this config file in the root your site project (e.g. as _siteGenConfig.json). When executing JekyllJS, the code will take that folder as the site path to start discovering and parsing files.

Running JekyllJS

I compared the generated site using an SVN diff, and aside from the Date and difference in highlighted code, it matches out. If you try it and see something, let me know.

node app.js | "./node_modules/.bin/bunyan" -o short

node app.js serve | "./node_modules/.bin/bunyan" -o short

I've completely changed how to run JekyllJS and generate your site in lieu of it supporting CI/CD environments. Previously, you executed code from the JekyllJS folder, which didn't make any sense. Now, you create your config file in the root path of your project, then create a new npm project and install it as a dependency:

npm install --save git@bitbucket.org:divillysausages/jekylljs.git

Once that's done, you can create scripts that will generate and build your site, and optionally serve it locally, using npx:

"scripts": {
	"build": "npx jekylljs ./_siteGenConfig.json",
	"serve": "npx jekylljs ./_siteGenConfig.json serve"
}

When running this in a CI/CD environment, simply deploy the _site folder to S3.

Get JekyllJS

You can find the code over on Bitbucket, and you can install the dependencies using npm install. Also on site is the liquid code that I use to generate my tags, archive, and feed.xml if it's something interesting to you.