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:
A good preprocessor, generator, or template system.
A good build system, but one that could be ad-hoc and hacked together in
a dynamic language
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
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.
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.
on how to comply with it.