A Note About Static Site Generators
One of the things I like about static site generators is the ability to write content in more human readable/writable formats like markdown and asciidoc and then mix it with layouts of your site. This way your site’s content isn’t tied to its presentation, which can be changed with themes. I’m a big proponent and enthusiast of themeability.
In basic principle of operation, all static site generators perform the task of taking markup content or raw html and mixing it with appropriate html templates to render final html site. The differences between the various static site generators available is in terms of support for
-
markup formats
-
template types and rendering engines
-
extra features like tags, feeds, archive, data files
-
plugins
-
flexibility of site structure and content
The Differences Explained
I’m not going to do a very detailed feature by feature comparison. This is about the things that came across my way as a noob and changed my options. Jekyll’s plugin functionality means there will always be some plugin to fill a void for whatever is missing. What I’m going to talk about though is the core architectural differences because these can hardly be undone and make a lot of difference.
Naming Scheme and Folder Structure
Jekyll imposes a strict naming scheme for your posts: YEAR-MONTH-DAY-title.MARKUP. The date here can be overridden in the YAML front matter though, so this requirement feels rather redundant. These posts all have to reside in the _posts folder without sub folders. Their output location depends on the permalink variable in front matter. Similarly drafts go in _drafts folder. All other files go anywhere else and maintain their folder structure in the output.
JBake doesn’t impose any naming scheme. In JBake all types of content goes in the content folder with whatever hierarchy you want which is retained in the output, along with file names. Posts and Pages are distinguished by type field and drafts are indicated by status field in front matter. The advantages are:
-
The source folder gives a complete picture of the output.
-
File names become permalinks.
-
The folder structure is not tied to JBake.
Templates
Jekyll uses Liquid template engine by default. The templates for mixing content with html are contained in _layouts folder. But the html fragments that get included in layouts are contained in _includes folder in the site root. Two folders doing one job is clutter to me. This is the default configuration which I think can be changed to point them both to the same folder.
JBake keeps templates outside the content directory in templates folder. It supports FreeMarker, Thymeleaf, Groovy and Jade. If you need to port an existing template Thymeleaf is an excellent choice. I have used it to create the theme for this blog. For greater power you can use Groovy.
The default template in Jekyll uses absolute addresses so you’ll have to run in server to render properly. JBake uses relative addresses so simply opening the index.html file will work too. Although this is a minor caveat it still was important for me.
Plugins
JBake doesn’t have plugin functionality yet. It’s in the making. Jekyll uses Ruby gems as plugins. In many themes I got plugin errors even with bundle exec. Sometimes a specific revision of a plugin wasn’t available at a Github repo. I came across too many such instances and then finally gave up trying. A Ruby guy might find his way but I wasn’t interested in trying.
Summary
I must confess that I searched for JBake before I had been even half way into learning Jekyll. Being a Java developer I felt compelled to find an alternative that ran on the JVM. Although I didn’t look into JBake until I encountered these caveats in my local Jekyll blog.
Overall Jekyll imposes a lot of its own baggage onto your content in terms of folder structure, post naming, and too many folders. JBake is not as powerful as Jekyll yet but it is also not that intrusive. Further JBake has out-of-the-box support for highly varied template engines. I must point out that there are alternatives such as Hugo, Pelican and others. I briefly looked at them. Hugo is also as powerful and intrusive as Jekyll. Pelican seemed more flexible. In a future post I plan to compare all the mainstream static site generators to highlight their main differences.