sssgen: Make static websites simple again

I've been asked to implement fairly complicated websites (, using static site generators, specifically Jekyll and Hugo.
The idea of a "static site generator" is pretty straightforward. The concepts of "front matter" and "templates" can be understood by anyone remotely technical in less than an hour. A static site generator, at its core, isn't much more than a fancy way to combine front matter and templates. But as anyone who has had to use either Jekyll or Hugo would attest, it gets very complicated very quickly.
What the marketing material for Hugo and Jekyll doesn't tell you, but will become apparent to you if you need to use either software for anything more complicated than a personal blog, is that Getting Shit Done in Jekyll/Hugo is surprisingly hard when your use case doesn't fall cleanly within the set of things that they are designed to help you with.

"Convention over Configuration"

The mantra "Convention over configuration" is something that every person involved in web development has heard. It is the idea that instead of having to repeat the pattern for say, loading and storing user information to a database, every time you need to do it for a new project, the software you are building on top of should give you a way to do it.
So in theory, it means that you spend less time programming (and debugging) motifs that you will reuse again and again for different projects. And as a side benefit, if you have to work on a project that is built on the same software, you don't have to relearn how everything is done - it will use the convention.
This sounds great, but it is my experience that these advantages are often outweighed by the problems presented by the idea of "Convention over Configuration".

1. The convention is very complicated, maybe undescribably so

The convention is never accurately or completely described in the documentation. Who can blame them? In fact, the description of how the software behaves, for sufficiently complicated software, may be equivalent to the program listing. At some point, you will have to read the source. Unfortunately, it's a virtual guarantee that any software which attempts to solve all your problems for you, has hilariously copious and meandering source code. Good luck understanding it.

2. The conventions are sometimes just baggage

As a corrolary of that, for the kinds of things I find myself doing, understanding the conventions to the extent that I need to implement an idea is much more work than what I stand to gain from the abstractions I am afforded. In fact, there is a large set of ideas which it would be reasonable to use a static site generator for, but are made unnecessarily complicated by Hugo/Jekyll due to how limiting the conventions are.

3. The convention treadmill

When the software updates, the conventions will change. In the worst case, no one knows what part of the convention changed or how, and you just have to discover those changes for yourself as you find parts of your project which don't work correctly any more. If you are very lucky, and the maintainers are feeling very magnanimous, there will be an error or warning message.

4. Every convention is a unique snowflake

Every software's set of conventions is different from any other project's set of conventions. It is like learning a new programming language for every different kind of thing that you want to do.

sssgen: "Configuration is Cool"

I wrote sssgen, the simple static site generator, to prove that "Configuration is Cool".
sssgen is 200 lines of straightforward Python. In a nutshell, all sssgen does is aggregate data found in frontmatter (YAML), and then funnel that data through your templates (authored in Mako).
You'll look like a smooth operator when you are programming things to do exactly what you want rather than googling ActiveRecord error messages. Secondly, you'll feel more relaxed because if something is wrong, you know it's your fixable mistake, and not the software you built your project on doing something wrong which may never get fixed.

"So what, Jekyll does that too."

The devil is in the details. In Hugo/Jekyll, many of the seemingly critical, core, details of "how is YAML aggregated?", "how do I access that variable from the layout?", etc., are commonly under- and mis-documented, and are often not even particularly well-defined. Arguably, the semantics of YAML aggregation is the most fundamental aspect of a static site generator. Why shouldn't it just fucking make sense? That is what I set out to do with sssgen.
For sssgen I wanted my mental model of how the static site generator works to be very simple and predictable. That's why sssgen is no more than a few good choices (Python, Mako templates) coupled with a dead simple execution model. It's simple enough to make blogging easy, yet it's also straightforward to generate contracting invoices with it.
Try it out.