I have a number of "static" microsites, in the sense that they're just plain old HTML with a minimum of Javascript supporting their operations. The oldest one is the Journal Entries site, which has been a Markdown archive of my vast and adult space opera since 1995 or so... which is quite a long time! It's had a number of generations since then; the first version had a simple perl-to-html converter, the output of which I would hand-edit, along with the index page. Recently, I got it into my head to revise them, and the change has amazing.

In 1995, Markdown didn't exist, so I was using an ad-hoc definition that I colloquially referred to as "Usenet emphasis mode," since it was more or less the same syntax I used when posting the stories to the text-only Usenet forums.

It's next life was in Emacs Muse, with a lispy header (semicolons in the first column) to describe the content, and now it's Zola Markdown in its current form, which is simply that every story has its own Markdown file with a TOML-based header to describe the story's metadata: title, publication date, order in the series, and so forth.

I was looking for a replacement tool when I found Zola. I've been growing steadily disillusioned with the quality of Python3's backward compatibility, and the breakdown I experienced trying to get Python3.10 to run the generator made me insane. I considered Hugo, but settled on Zola, if only because it's written in Rust rather than Go, and I'm a partisan about those two languages.

The Python to Zola distinction is huge; generating the site went from two minutes to nine seconds, and there's auto-reloading when in development mode.

I'm preparing another, more technical, document for many of the things that I learned while I was doing the conversion, but I wanted to capture some process notes here, if only for myself.

Paper and Prototypes

A static website is, properly, just HTML (and all its assets, like images and fonts), CSS, and maybe some Javascript. The challenge of maintaining a website with a bunch of different serials, some SF, some fantasy, and even one contemporary, is that I wanted them all to have a separate and independent look and feel. This approach is known as "white label", in that the skeleton of the website is established but the branding is left to a third party.

The other thing is that this must be super-easy to read, since that's what I'm asking my audience to do. So I have to pick fonts and manage a layout that both communicates the nature of the stories and is still highly pleasurable to read for long periods of time.

So here's my basic advice: forget Figma. Draw your site on paper, then make prototypes, then part them out to the template engine. Do the same thing with your CSS. Iteratively identify the components of your site that are common between all of them, and push them up the stack from specific pages to the more general cases. Leverage your SASS skills as much as possible to avoid repetition.

On the other hand, do not use SASS for your theming. Use CSS Custom Properties instead. Put those properties as an includable header.

Just as importantly, use Utopia Scaling for your font sizes and spacing, and be as disciplined as you can about using them. Utopia tells a white lie about the "without breakpoints" bit; you'll still need breakpoints to decide when your site is going from a two- or three-column layout to a mobile phone single-column layout with an extra footer or maybe a drawer. When you have an unusual scaling issue, use CSS calc() to multiply your Utopia-provided sizing position.

If SASS doesn't like your use of clamp() (because it conflicts with their own), you can make the SASS compiler happy with this bit of annoying magic:


It seems that SCSS ignores everything inside a calc(), and all web browsers that understand calc() elide a calculation that doesn't do any calculation as an optimization, so that bit of code doesn't waste any CPU in the process.

Lessons Learned

These are all lessons I've had to learn time and again, and I wish I could say that I didn't just barrell into the project on day one and assume I could hold it all in my head... but I did. I mean, I had the original Python templates, and they were in Jinja2, and Zola's own templating language is a derivation of Jinja2, how hard could it have been?

But I was an idiot, as usual, and did exactly that. I think the whole project took about 20 hours, and a lot of that was refactoring my nonsense after I'd written it. You'd think, after 25 years of maintaining this site (and the stories themselves turn 32 years old in August), that I'd have learned that lesson.

Maybe next time. I have other sites to convert, and none of them are "white label," thankfully.