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.
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
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
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.
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.