Notes on writing a static site generator

Why write a static site generator?

  1. Because dependencies in small projects are overrated.
  2. For Marie Kondo reasons. It makes writing and maintaining my site pleasant and joyful. Other SSGs might be fine pieces of software, but they decidedly did not spark joy for me.

What have I learned?

  1. Addressing some problem you actually have remains a great way to learn software.
  2. Here's a testing philosophy: "Test the formal correctness of smaller parts of your code with suites of small tests. Test that these parts are interoperating correctly, and handling the right data, with other tools: smoke tests, dashboards, etc." You probably don't literally believe this, but a lot of us default to something like it. The SSG has, instructively, obliterated this view. Pytest is a wonderful tool for, e.g., ensuring that all my (relative) links work.
  3. The SSG should be able to handle tens of millions of words or tens of thousands of posts. Not more, ever. (Alas.) The site might need to handle unpredictable and large scale, but its construction won't. Utterly divorcing "this is well-made software" from "this software can handle arbitrary scale" has been instructive. Remarkably few problems go away!
  4. In many applications, separating the logical form of data from its persisted form is essential. Here, less so. I went down a wrong path of instinctively applying some patterns to accomplish that. It was an instructive failure, both psychologically ("why did I do that so reflexively?") and technically ("why don't I need this here?").
  5. More generally: my other work is not at all like writing an SSG. Taking on a real project with a new structure has been eye-opening. I often see advice to stay sharp by learning new languages or new tools, usually with toy projects or tutorials. I find it much more illuminating to do diverse and real projects--usually, but not always, with the tools I know. The cognitive benefits of tackling a real problem are (for me, at least) much greater than those of exposure to a new tool. And I find it natural and pleasant to let technical needs in real projects drive me to learn a tool, rather than vice versa.

However many rough edges remain, the project is a success. I have a tool I can use and improve indefinitely. And it really hasn't taken that much longer than learning to use some existing SSG. I am struck by how many Web sites outgrow the software they're made from (or seem indefinitely and tragically constrained by that software). I'm pleased to eliminate that category of problems.


Home page