Imaginary Text

Static Site Trials

JMaxJune 26, 2023 colophon

Welcome to my new blog. This is built using Eleventy, using as simple and low-tech an approach I could muster: markdown content, a handful of templates, and a simple git push direct to my webserver (at Reclaim, natch).

For many years now I have been writing – everything – in markdown, in plain text, and using Pandoc to do most of my publication things. At the same time, all of my web presence was in Wordpress, which is on a different planet from the markdown aesthetic.

In 2019, with excellent help from my friend Paul Hibbitts I launched our Pop! Public. Open. Participatory journal on the Grav CMS. Grav isn’t a static-site generator per se; rather a flat-file CMS. Which is to say that as a website, it’s more ‘live’ than ‘static.’ But the content in it is still plain markdown + YAML, which suits my writing+editing workflow aesthetic. Content gets prepped as markdown, pushed to GitHub, and from there the site is populated. It’s clean and crisp and pretty bomb-proof, and I was able to build the entire theme for the site from Grav templates within a few days. Kudos to Grav!

Grav still has a fair bit of organizational overhead, so I started to wonder about simpler ways to publish markdown to the web. By now the mainstream way to do this is probably GitHub Pages, which is to say markdown files on GitHub, published through GitHub’s proprietary system, using Jekyll. It’s stupidly simple to get started with, and there are a million websites built this way that one can borrow from. But I wanted to avoid GitHub, because it’s almost certainly an exploitative property for Microsoft and it undoubtedly feeds directly into OpenAI, which I’d rather not contribute to. And I think it’s time to start building “the new web” as people are saying these days (I installed an RSS Reader the other day, too, for the first time in a decade).

So I looked at a few things for this website. First off, I wondered if I could use Git locally – between my laptop and a web server, without going through Microsoft, and it turns out that on the always-wonderful Reclaim Hosting I can do exactly that without too much trouble. So that means I can build a static site locally and push it directly to web hosting at Reclaim. Which suits me perfectly.

So how to build a site? I cringe at having to learn a whole new system. I didn’t want to learn Jekyll (Ruby on Rails); I didn’t want to learn Hugo (Go); but all the cool kids are talking about Eleventy these days as the hot new thing… supposedly simpler and faster (it’s built on Node and Javascript, which doesn’t frighten me as much as it probably should).

So I installed Eleventy on my laptop, which was stupidly simple. Wrote a markdown file, edited a config, and ran a command, and voila – a website, which I could then push via Git to my site on Reclaim Hosting. Hooray.

Then I got into developing it into a site that I wanted to live with: a blog and a theme and so on. Of course my default approach is to start at the bottom level and build up, so I found the simplest, lowest-level tutorial I could find and began there. Sure enough, before long I had a folder full of blog posts and a homepage that listed them in reverse-chronological order. And I had a decent start on a style and a theme, and all seemed well.

Then I got into the weeds, and it made my head hurt. Simple is as simple does, but Eleventy achieves its simplicity and speed in part by leaving a number of niceties un-developed; if you want them, you just write some extra code in the magical eleventy.js file that quickly begins to look a bit like a giant code dump. Case in point: publication dates. Eleventy knows what a date is, and seems happy to pull a date from your file or from metadata. But it has no concept of a time zone, so if you want a nice, readable, localized date to appear on your site, you have to write that bit yourself. It’s not hard, but it’s enough, and a bunch of such cases adds up – at least given the from-the-ground-up approach I was taking. I started to look at writing a lot of little bits of javascript in order to make it do the things I wanted it to do.

Around this time, I saw a piece that Tim Bray shared on Mastodon, on “Hype Cycles” that was a bit of a rant against the endless cycle of following what the cool kids are doing at any point in time (the article begins with “XML was gong to replace everything” – and I could relate).

Reading that, I reconsidered Eleventy and, in a fit of minimalist pique, said to myself, Self, I’m going to write my site generator with Pandoc and build the website with a good old bash script and I’ll be resisting the hype and also making the thing more future-proof by embracing the past, as one does. Pandoc being the greatest text processor ever, and it even has a decent templating language. So, a couple hours later I had some nice Pandoc templates that made nice looking blog posts, and I started thinking about how this bash script was going to work to build a home page and index to the site. I thought about a special pandoc template to just expose the metadata from the posts, and sort them, and then, and then…

And I began to realize that while this was all technically possible, there were architectural reasons why this wasn’t optimal, and that, in trying to reinvent everything (e.g., blog staples like categories, tags, archive pages, RSS feeds) in my bash script, I would in effect be re-treading all the ground that the people who built Jekyll, Hugo, and Eleventy had already trod. And that made me feel somewhat silly.

So I went back to the Eleventy website, and I found Raymond Camden’s slightly higher-level tutorial for building a blog in Eleventy, and, well, here we are.

That, friends, is what makes this thing work. It wasn’t more than a couple of hours, altogether, to follow the tutorial and build the site (five liquid templates, 60-ish well-commented lines of the eleventy.js file, an RSS feed) and that’s about all it took. I spent many more hours fiddling with my CSS file, which is how I like it. Now to spend hours actually writing posts…