Today I engaged in a little “fall” cleaning. This post is somewhat technical, a changelog explaining, if only to myself, what I did to my story collection this Fall to clean up some internal details.
The wonderful consistency of my story mini-sites is due to a very simple thing: I’ve been using rendering templates for them since the very beginning, going as far back as 1993. The first generation of scripts were written in Perl, and respected what was then thought of as “Usenet Emphasis Text,” using asterisks and underlines to provide that emphasis. That sort of thing has evolved into Markdown and its familiars, and over the years my own text repository has also evolved to match those standards, with satisfying results.
Two versions ago, the entire site was actually written in Django, a web application framework written in Python, and all of the stories were stored in the database. That was silly, of course, but it was what I knew professionally and I thought I was being cool at the time. For the previous version, I had torn out the Django but kept Django’s templating engine, named “Jinja2,” to render all of the HTML statically, which I could then upload to the server quickly. That worked well, but writing the code to keep it organized was a difficult task. I was, of course, up to that task.
I experimented briefly with one of the “industrial strength” static site generators, but I could not for the life of me get it to do what I wanted. The biggest problem is that it wanted to turn every story into a folder, so that the “nasty” .html extension wasn’t visible; but that meant that every story ended in a terminal /, which to me was unacceptable; since I started on the web in 1993, a terminal slash meant you were looking at an index or table of contents. It also wanted to downcase all of my URLs and remove all the punctuation. As much as I appreciate slug URLs, my URLs still conform to the “clean” standard, and they’ve been unchanged in over twenty years! I think I have a moral duty to keep them unchanged for, well, for as long as I’m alive and care to share my stories with y’all.
The experiment may have been a failure, but it made me realize just how much cruft was in my story engine. I re-wrote the entire engine and, sadly, abandoned my beloved Hy, switching back to base Python instead. The resulting engine is only five lines shorter, but Hy is super-compact compared to Python, and the current version is readable and even documented. It doesn't matter if Zola took less than a half-second and mine takes six seconds, if Zola can't get it right and I can. Six seconds is nothing, and more importantly, my engine is change-aware; if I add a story, the update time is in milliseconds, since only four files need updating: a new page for the new story, the table of contents leading to that story, and the neighboring stories so the "next/previous" links work.
The other thing I did was eliminate almost all of the old layout CSS. It’s 2020, for Cthulhu’s sake! The stories are now laid out with CSS flexbox and proper media queries. I haven’t touched that code in a decade, and it showed.
The other thing, which is more esoteric but still straightforward, is that the “date of publication” toggle on the Journal Entries page has been, well, I hesitate to call it “fixed,” but it’s definitely modernized, with the two table-building functions actually broken out into, functions with proper .map() internals for building the lines of the page, and the sort-order function itself has a lovely abstraction. All in all, I’m rather pleased with how that code looks now. Oh, it won’t win me any awards, but at least it’s no longer embarrassing.
You shouldn’t notice any changes with the readability of the website; if anything, the removal of so much cruft should make it more readable, not less. And it still renders pretty well on phones, in case you want to take your sci-fi smut on the road.