A Static Site

Background

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.

A Plan

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 &amp; 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.

Implementation

This might change over time and I'll aim to keep it up to date - mostly so I can remember what I've done.

Writing

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.

When I'm editing locally I preview my changes in a browser with python3 -m http.server. I have a script in scripts/fixup.py that currently just makes sure that the <footer> block is consistent across all pages.

Publishing

I'm storing the content in Git, using Sourcehut for my source of truth repo. I'm hosting the actual site on a VM I keep running in Google Cloud. It's static, so I'm tempted to look at some specialized static site serving, perhaps deploying automatically on a commit hook, but that's the kind of thinking that stops me actually shipping a new site.

Future Ideas

This is sort of a to-do list. Or at least a to-investigate list.

Syntax Highlighting
If I end up writing pages with a lot of code I should try something like highlight.js.
Static Serving
Take a look at some static serving options like:
Deploy hooks
I should be able to update the site just by pushing from my laptop without needing to either have a deployment tool handy or logging into my server to check out the code.
Analytics
Do I care how many people see my site? Who they are? Should I just run Google Analytics?
Feeds
If I actually write articles, maybe I can generate RSS or Atom feeds based on git history. That sounds fun.