If you're reading this then I actually published a new web site. For years I've been meaning to update my web site, but the options are endless. There are lots of static site generators that seem really neat, but whenever I try them I end up spending a lot of time tweaking and customizing them. What I intended as a writing or at most deployment exercise turns into software engineering - which I love doing - but it never ships.
I had the realization the other day that instead of a static site generator, I could write a static site.
I know HTML. When I've tried SSGs I'm frustrated by their imprecise and
inflexible translation from Markdown or whatever into actual HTML. I
prefer writing <i>foo</i> than
*foo* because it's clearer and less ambiguous. Writing
Markdown I invariably find myself what the rendered output looks like
(at least in a browser, if not reading the source) to make sure that my
I've expressed my intentions correctly. There are some sharper edges -
I'll have to write &
if I want an ampersand, but I think I can manage.
While I'm planning to write the content directly into HTML files, it makes sense to have tools to check for mistakes, help me write the content, and even perhaps generate other representations of it. For example, if I decide to publish an RSS or Atom feed I could generate that from the HTML files and commit history. But I think I'll check all of that in - so that what's under source control is what's served.
I also don't object to dynamic content. I might find it useful to use JS, even with some server-side code to enhance things. But this will all be enhancements. It'll be out of the path of me sitting down to write some words.
This might change over time and I'll aim to keep it up to date - mostly so I can remember what I've done.
I'm using Visual Studio Code on my laptop to write the site. If I edit it server-side I'll probably use Vim. They're both good for editing HTML, with syntax highlighting to keep me from making the stupidest mistakes. There's even a decent spell checker for VSCode. For previewing while I edit I just run a simple local web server.
I'm storing the content in Git, using Sourcehut for my source of truth repo. Right now I'm using Firebase Hosting to host the static files and Sourcehut builds to deploy each time I push.
One of the great things about using code or templates to generate content is that parts of the site that should be common across all pages can be implemented once and then applied globally. CSS stylesheets let me manage some of the visual styling centrally, but that only works if I can make sure that every page actually applies that stylesheet, and other common elements like navigation can't be managed through a stylesheet.
I've written an increasingly complex fixup script that
checks that various invariants about documents are held. Mostly headers
and footers right now.
Site navigation in a database-backed site is just a query. Static site generators typically look at specially formatted YAML frontmatter to generate this stuff. I'm too lazy (and unreliable) to maintain navigation by hand so I took an approach similar to the SSG one, but instead of special data formats I scrape title tags out of HTML pages.
This is sort of a to-do list. Or at least a to-investigate list.