I've been thinking a lot lately about the state of the internet and web tech. It's highly likely that you, dear reader, have heard of Dead Internet Theory. If not: the gist is that the vast majority of traffic on the internet comes from bots and that most of the actual content (what a vile word) is algorithmically-generated, increasingly by generative AI. I want to believe that this theory is false, but as far as social networking goes it seems increasingly plausible. However, it's worth trying for a different future — one that brings power back into the hands of the people and not the megacorps. Ream is a small contribution toward this goal.
I grew up as the Internet did; I had dial-up in 1995, I used AOL Instant Messenger until they shut their doors, and I participated in forums before Reddit was ever a concept. The obvious promises of the Internet have come true: the world's information at your fingertips, and realtime collaboration with people halfway across the globe. Other promises, things that were once true, have faded with time. It's no longer easy to carve out a place of your own on the internet; blogging gave way to social networks and micro-blogging, and with it the sense of having a private corner you could personalize. The good news is that we still have the power to have this back, it just takes a bit more effort now that free, shared hosting is a little harder to get your hands on. I'll concede that there are challenges that you'll face today that weren't concerns back in the early days: AI scrapers, increasingly draconian access and content laws that vary by country, and coordinated harrassment campaigns. It is still worth it to try even in the face of all this.
Ream
Ream is just one piece of this, but it covers a paramount concern: "how do you actually build and manage a site?" I designed Ream having had experience with a number of site generators and different technologies over the past few decades, and while I built it primarily for myself, I am releasing it publicly on the off-chance that someone else will use and enjoy it (and maybe even modify it for their own use cases).
The criteria I worked from are as follows:
Fully Static - I've used many dynamic CMSes over the last two decades and the power they provide comes with a few major downsides: difficulty of deployment, resource cost to generate pages, and overall security. I'll admit to not knowing the exact state of free hosting right now, but most free or extremely low-cost hosts support a very narrow set of dynamic languages (usually just PHP) and may not provide the extensions a given CMS needs. The vast majority of CMSes are also written in interpreted languages which have a very high cost-per-page; you'll only be able to serve a fraction (usually 1/100th or less) of the requests you could if the site was statically generated, especially if a database is involved. Lastly, a static site is going to be a much smaller attack surface than a full appplication will be and thus have a smaller maintenance burden.
Emphasize Core Web Technologies - Most site generators lean on some document format that is not HTML for their input. They're ultimately going to generate HTML and the templates are written in HTML, so this just increases the burden on the user. I'll admit to HTML having some rough edges for just writing a document (e.g. entities, tag nesting rules), but they're learnable and surmountable. I personally find it a lot easier to work with HTML than Markdown, for example, because HTML is very exact and there's no implicit rules that have to be worked around to get the output you want. This also opens up the door to more interesting CSS styling decisions due to working at the same level as the output.
Relocateable - The vast majority of static site generators assume that a site will be located at a specific path (usually the root) on a web server. This is great if you have control of a full domain or subdomain, but there's free hosting that just gives you a sub-directory somewhere. HTML and browsers support relative URLs so I leaned on this fact to generate fully relocateable output. It does require a small amount of template markup, but the extra mental overhead is worth not having to think about changing a base URL and then regenerating the site if the URL scheme changes. That being said, RSS requires a base URL to be set (URLs must be absolute) as part of the spec, but this is just a small piece of the whole.
Minimal Templating - Most static site generators have full templating languages that allow looping, if-statements, and arbitrary code callbacks. These are fantastic features if you're 1) a programmer or 2) building a site for an organization. For the average user these kinds of template systems introduce a significant amount of complexity. However, templating is a requirement if you want a consistent look and feel and the ability to focus on the actual pages and posts on your site rather than copying boilerplate everywhere. To that end I've built a very simple templating language that should be enough for most people. It does support nesting for users that are determined to do complicated things — there's a directive that reads from the
config.inifile and one that can insert full HTML snippets. Templates are also processed up to a maximum nesting of 10, which enables a few, neat party tricks.
Get It
You can download Ream from the releases page. There's only pre-compiled binaries for Linux at this time, but the source is also fully free and open, so that's an option for anyone with a working Rust compiler.
Learn It
You can visit the Ream Doc Site to learn more about how to use it, get resources for HTML and CSS, and even about alternatives if it's not quite your speed. As a point of pride: both the doc site and the one you're reading right now were generated with Ream.