My Dream Static Website Generator

I'm on the hunt for a simple tool to build simple websites. In my last post I explained a bit about what I mean by that and why I find the existing options unsatisfactory. It got me thinking about what my requirements are. I think it's good in general to think up front about how software should work. It helps me quickly pass on existing solutions before wasting tons of time learning a new thing only to discover it can't do what I need (because I didn't know what I needed until it was too late). It also helps me make better software.

I've made several different static site generators with different approaches and every time the reason I stop using them is because there's some feature I want that would be very complicated to add because it's at odds with some fundamental way the original system was designed. After a few iterations I feel like I finally have a pretty good grasp on my requirements, which is at least a start. The rest of this post explains what they are.

Advanced markdown processing

Most static site generators render markdown to HTML, but most don't handle any extensions to basic markdown very well. I have some special things I need my static site generator to handle, including:

Use open standards and best practices

By this I mean the final website should have no accessibility issues, no performance issues, and nothing extra being downloaded that is not necessary to load the text on the page. It should also use semantic HTML with all the right head tags to render properly in search results and social media. It should be styled with modern and minimal CSS, and, of course, have no JS for static content. Ideally all of these things would be checked on build so that an inaccessible, slow, bloated website simply cannot be made with this tool.

Arbitrary data access

My main complaint with basically all of the current options for generating static websites is that the content and templates are all intermingled — severely complected, as a Clojurian would say. There are also major usability issues as a user trying to add new content to a website. Content and website structure should be fundamentally decoupled. That means:

Blogging features

These should ideally fall out of the flexible requirements for accessing data I just described (for free), but there are a few specific blogging features I always need, so they get a special mention here:

Flexible templating and markup languages

I write mostly in either Org mode or Markdown, occasionally also Asciidoc. And sometimes I make a page that's so unique and incompatible with my existing layout I write it directly in HTML. My static site generator should be agnostic about markup language and support all of these seamlessly.

For designing the layout of the website it should use a well known but simple templating language. Something like Mustache, Liquid, or Nunchucks would be good, or considering my affinity for Clojure maybe Selmer or even Hiccup, though that might be prohibitively weird. The main point is that it should be simple to use and narrowly focused on templating. Concerns about munging data and post-processing content should be entirely separate from developing the layout of the website.

The layouts should also be sufficiently flexible to allow granular customization down to the page. There are many special cases where I want to include one extra tag in the head for example, or something special in the footer. The layout should support these kinds of customizations without requireing janky hacks that break the semantic grouping in the HTML.

Smooth development experience

Speaking of developing the layout, I'm a spoiled millenial web developer and want a smooth developer experience. No janky scripts or custom build chains. I want a single command out of the box that I can run to get a development server that will watch my files and auto-reload the browser when they change. I'm not entirely sold on CSS and JS variants that require pre- or post-processing, but I think they're useful and ubiquitous enough the tool should probably support these as well.

Things like Less and Tailwind will probably fall out of fashion soon enough, but auto-prefixing and dead rule pruning are probably here to stay and should be included out of the box. Similarly I suspect the compile-to-JS language du jour will continue to change every year or two, but minifying and fingerprinting scripts are kind of minimum best practice now and should happen automatically. Same for image optimization to be honest, but now I'm really dreaming.


This is my wishlist for my static website building experience. It follows a broad general pattern of being very flexible with data and the underlying model(s) the site uses, whilst being very rigid and prescriptive about standards for minimal markup. This fits my overall philosophy of programming. I basically think develoeprs should lean heavily on existing standards and best practices where they exist, so that the majority of development effort can be spent on the (ideally small) part of the project that truly is unique. One of my biggest complaints about the tech industry generally is how much time we waste reinventing wheels.

Thinking through how everything should work in advance like this is really helpful for me. The more software I write the more convinced I become that we should be spending vastly more time thinking about and designing software than we do. I get that there's a trade off between doing things well and getting things done, but there is also a difference between perfectionism and valuing quality.

So, hopefully someone will find this blog post and build my dream static website generator. Failing that, I will probably start working on yet another attempt of my own as my next side project.