Log in

No account? Create an account
The Despair of a Static Site Generator Creator - Shlomif's Technical Posts Community [entries|archive|friends|userinfo]
Shlomif's Technical Posts Community

[ userinfo | livejournal userinfo ]
[ archive | journal archive ]

[Links:| Shlomi Fish's Homepage Main Journal Homesite Blog Planet Linux-IL Amir Aharoni in Unicode open dot dot dot ]

The Despair of a Static Site Generator Creator [Dec. 21st, 2017|08:48 pm]
Shlomif's Technical Posts Community


[Tags|, , , ]
[Current Mood |productive]
[Current Music |Cimorelli - Problem]


The main take-away from this essay is that I cannot in good conscience recommend against writing your own custom/ad-hoc/home-grown static site generator ("SSG") based on some lower-level tools, rather than going through the trouble of learning an existing open source one. Feel free to publish your own creation as open source as well, but you should anticipate that it is most probably not going to be popular.


(A crowded room in a support group session:)

Me: Hi all! My name is Shlomi and I wrote several of my own static site generators!

The others: Hello, Shlomi! We all love you!

(By inspiration from Kilmo.)

Yes, I wrote several static site generators (follow this link to learn more about SSGs in general and the motivation for them), and while they have served me mostly well, I suspect few people use them except me. They all were built on existing preprocessors or template systems, some of which could be considered static site gens in their own right.

In this essay, I'd also like to give some historical perspective.

Requirements for a static site generator

Your static site generator should have:

  1. A good preprocessor, generator, or template system.

  2. A good build system, but one that could be ad-hoc and hacked together in a dynamic language or similar.

  3. The other best practices related to software dev, such as using version control, or CI.

How it started

I originally learned how to write HTML from an article in an Internet magazine that my father bought me back around 1995. In 1996, I started working as a web developer for Cortext Web Design where I wrote HTML or CGI scripts generating it server-side in Perl 5 and learned some other technologies.

After a while, I set up my own web site consisting of several hand-maintained HTML pages and maintained it for many years this way. You can find an old 1998 snapshot of it.

A bit later while working on the Israeli Group of Linux Users' site, I wrote my first static site generator, in PHP (version 3 if I recall correctly) where it used PHP to preprocess the pages offline and generate a static site. While it worked, the use of PHP for that seemed suboptimal.

The birth of Latemp

Website META Language or WML for short was a relatively early and open source offline HTML preprocessing toolkit that proved to be somewhat popular. I learnt about it in a news digest that one of the Linux-Israel members posted, and eventually decided to try it out. After writing some smaller projects with it, I ended up converting most of my sites to it. This resulted in some duplicate code, which I decided to extract into Latemp (a play on "Template" and LaTeX), which was a static site generator that was marketed as an “offline content management system”, which in turn caused me to be contacted by some people seeking a server-side CMS such as Drupal. To be fair: at that point, I wasn't aware that "static site generator" was the more conventional term.

WML and Latemp proved to be powerful and flexible, but on the other hand, were relatively slow in comparison to other alternatives.

I should note that I ended up becoming the maintainer of WML.

Facing some criticism

Back in the early to mid-200xs, a fellow Linux-IL worker kept telling me that I should not generate static HTML sections of our sites and instead should use PHP on the server side, implying that static HTML was no longer a valid approach.

Furthermore, when a different contributor volunteered to create a site and I told him to use static HTML and not depend on PHP, he asked me if he could use HTML frames. Turns out that despite his years of experience in PHP, he didn't realise that static HTML can be generated from templates, something I had realised years ago.

Nowadays, with the advent of Jekyll and other popular SSGs, many clueful web-developers are more informed about them, but OTOH, someone recently argued that Jekyll was the only valid alternative to server-side PHP, and not SSG in general.

Recent developments

Some time after GitHub started, it started offering the “GitHub pages” service for hosting static HTML sites, and shortly afterwards Jekyll and other SSGs emerged and made the concept of SSG more well-known. GitHub also allows previewing files in several formats as rich text HTML directly from the repository view.

I tried using Jekyll for Vim-Begin and ended up not liking it out of finding it too opaque and hard to use. As a result, I ended up creating a new SSG for Vim-Begin based on Template Toolkit. Later, I used it for the www.linux.org.il site. One possible indication of its ease-of-use is that it received some pull-requests from other contributors on GitHub.

Moreover, it seems it is much faster than Latemp, as well.

My sites now incorporate such industry best practices as using version control, having an automated test suite, and using a Continuous Integration service. They should also be mostly valid HTML/XHTML markup. However, the Latemp-based one take a while to build and sometimes involve quite a few levels of indirection and preprocessing. So I cannot recommend using Latemp, due to this and because WML is quite complex.

I also found the hybrid approach of both an SSG and a server-side CMS taken by ikiwiki appealing and used git repositories containing markdown files for a good effect.

Like I said earlier, I find that writing your own custom SSG is not hard, and probably less hard than learning an existing one. Also see this. So I expect more of them to emerge in the future.

Someone on chat told me he believed that SSGs wont survive the trend towards component-based client-side frameworks (such as React.js or Vue.js) but I'm skeptical of such predictions and in my time saw several similar ones not materialise. Also see this funny critique of modern JS.

So static site generation has proven to be a valid approach in the past and into the near future. However, I maintain several sites using my own custom ones (with all their quirks) and don't expect them to be of much interest to anyone except me and future maintainers of the sites. And here lies my despair.


You can reuse this entry under the Creative Commons Attribution Noncommercial 3.0 Unported licence, or at your option any later version. See the instructions on how to comply with it.