Lately, I've been thinking about, if not troubled by, the increasing complexity of the web. While I don't take much stock in the long-term impact of self-indulgent projects like Gemini (and don't get me wrong, I have no problem with people playing around with tech they find cool just because they can), I do share the spirit of the project and others on the web resisting an ever-maddening complexity of the web — even though a major part of my professional life involves making sophisticated, robust webapps.
I think the horse has long left the barn regarding the overall web's complexity, and things definitely aren't trending towards getting any simpler, but nevertheless, I thought I'd spend a bit of time on my own manifesto of sorts, and explain how this site came to be.
Down to Basics
The core of the web is two basic standards: HTTP (and HTTPS, which I suppose isn't all that simple, but it's also essentially free these days) and HTML. You make a request for a resource, and you get it served to you. Often, the document is an HTML document. The modern web has expanded, extending functionality via endless technologies, but the fundamental core is the whole1 of this site: request a resource (more on that in a bit), get a file served to you, and your client decides what to do with that file.
This doesn't really ever change. The web will always be at least this, so designing for simplicity is liberating — countless interactive doodads and their engineering concerns, wholly discarded, eschewed in favor of the basics.
Similarly, a simple site is an easy to maintain site. In addition to designing the site itself around the idea of simplicity, I made technology choices that make delivering the site's content a low-effort affair.
With that, let's look at some choices.
Markdown is a very simple text shortcut to writing HTML. Often, you can just write paragraphs and bulletted lists in a natural way, slam it through the out-of-the-box Markdown renderer, and get a perfectly decent HTML document out of it. Additional things, such as links, aren't much more work.
I've pretty much always hated writing HTML. A simple HTML template wraps the Markdown documents that make up this site, and I generally try to avoid ever touching the template. Sometimes2, I have images and figures provided via bespoke HTML — kind of a consequence of wanting things to look good or preferring some features that don't make sense in Markdown, but I try to avoid it as much as I can.
Thankfully, I haven't written a site with raw HTML in essentially forever. Probably not since high
school. Instead, I can write in a file that is essentially the barest form of my content, reusable
and easily searchable with
grep, transformable with
sed, manipulatable with
Plain old files
On the subject of *nix tools, it doesn't get much simpler than Unicode text files (especially ones that might as well actually be ASCII files). You can do anything with them — basic *nix stuff as above, index them, serve them in a raw format without the Markdown renderer, whatever. And you never need a specialized tool for it. And everything else can be just plain files in directories too. Here's a video of me defeating WarMech, and a text file of my video game collection. This screenshot of my laptop desktop is, specifically, a link to a symlink, the actual file residing here.
There are sites that I've lost to time, because they only lived in a database and I just didn't bother to back up the database before it got nuked, or the software to pull records and make content out of them is out of date, or whatever. It's hard to lose access to the most basic data files out there. Rather than representing the structure of the site in a relational database, files on the file system are the site. Images aren't blobs in a database, they're just sitting there on disk. A deeply-nested URL path isn't a slug in a post object's metadata, it's a directory structure with a file in it. Easy.
Now my site structure isn't abstract, it's easily grokkable (and replicable, and so on). I can see the meat of my site, in my shell or Dolphin, and manipulate it like it was any other directory or project in my home dir.
It has no place here.
The web, in the early days, was about the delivery of content, not aesthetics. It still is, largely, but aesthetical choices have mutated beyond "look and feel" to a whole new class of editorial choice about how content appears to the end user. This is somewhat necessary, but also a veto of the user agent's role presenting content on the web.
In an attempt to give power back to the users, I am keeping this site's stylesheets simple and straightforward, offering a couple basic options with some common stuff (colors, text sizes, page width) and quality of life fiddling (image size constraints). I've also added a plain style, as an experiment, which includes only the most necessary quality of life styling (such as the aforementioned image size constraints, because I'm too lazy to upload shrunken versions of logos, screenshots, etc.)
Git for Content
Maintaining site content in Git allows me to never worry about having it stuck in some inaccessible spot or proprietary format, and I get history for free. At some future point, I might even use it to publish an RSS/Atom feed, just because that seems neat.
I've written complicated personal sites in Django, complete with its ORM, flexible support for addons and middleware and extensions and so on, and every time I've done so, the framework eventually became a limiting factor over my constrained free time, and the site fell into disrepair. This site is backed by Flask, and is little more than an engine for reading in text files and running them through the Markdown renderer. At time of writing, I've called the site's engine v1.0.0 and I've authored 197 lines of code.
Flask is a great little microframework, for a very straightforward site.
- Be as *nix-ike as possible. Allow CLI tools and interfaces to work for the site as much
as possible — my IDE is
vim, aliases are symlinks, and so on.
- The site shouldn't look like an abomination in text browsers. ELinks is a first-class citizen, though Chromium is welcome too.
- Leave most decisions to the user agent.
- Don't HTTPify something the internet has a protocol for; accept email and mailing lists.
- Don't get crazy with styling (see also: leave most decisions to the user agent).
- Open source everything; such as this software.
Alright, there's an exception or two. These kind of hang off the site as specializations for a specific purpose (i.e. livestreaming video) off in a corner than anything germane to the site. ↩
Writing this article actually motivated me to turn on a couple more Markdown extensions and excise the
divtags in usage. Maybe I'll be rid of them for good. ↩