Optimizing for text-mode browsers

2026-06-02T00:00:00.000Z

This page is copied from the blog of Jared Krinke, the creator of Luasmith

I still use text-mode browsers (mostly w3m, sometimes Lynx), especially on old computers, because they're fast, use little memory, and don't take up much disk space. They also aren't funded by ad cartels, but that's not my primary motivation.

While the prior version of this site was functional in text-mode browsers (thanks to minimalist design and static HTML), I wanted to try optimizing for text-mode (and old) browsers first, both so that the site works great in those browsers and also as an exercise in simplicity.

Issues with the old design

While I liked the CGA palette of my previous blog theme in graphical browsers, it was unwieldy in Lynx and w3m because:

You had to scroll past a list of tags to get to the main content
The article list took up too much vertical space
The publish dates of articles weren't visually obvious

See for yourself:

Screenshot of the old design in Lynx

It was better than most of the modern web, but I didn't enjoy it.

Fixes

The obvious way to ensure text-mode users don't have to scroll past branding and navigation links is to put those features last in the HTML and have CSS display those items up top (CSS is generally ignored by text-mode browsers).

But I took a simpler approach and just dropped branding from all but my landing page and then moved the tag list to the end (and kept it there, even for modern browsers) on most pages.

Now, when you open the site in Lynx, you get to the content right away:

Screenshot of the new design in Lynx

(I also added an introductory blurb, but for the landing page I'm counting that as content.)

Article list

To simplify the article list, I decided to group articles by year, align their publish dates, and just not bother to show a (usually redundant) blurb. The result looks great in monochrome w3m:

The new, concise article list, as shown in w3m

Syntax highlighting

Pushing beyond reasonable affordances, I decided to use old school <b> and <i> tags for syntax highlighting, to ensure syntax highlighting was applied both on text-mode browsers as well as older graphical ones.

Here's functional syntax highlighting in Internet Explorer 6 (on Windows XP):

Syntax highlighting even works in IE6!

Dark mode

Unrelated to text-mode browsing, I took this opportunity to finally implement both light and dark mode:

:root {
  color-scheme: light dark;
  --lighter: color-mix(in srgb, currentColor 70%, transparent);
  --bg: color-mix(in srgb, currentColor 12%, transparent);
}

That's it. Rather than torture myself with choosing colors for both light and dark color schemes via media queries, I decided to try taking advantage of modern browsers' default stylesheets and then just crank up/down the amount of color (via transparency). I had toyed with this approach before, but Safari on iOS had a broken dark mode default stylesheet for many years (resulting in dark blue-on-black links). Fortunately, that issue finally got resolved, so I can unleash this questionable design upon the web!

Bonus benefits

One side effect of optimizing for text-based browsers is that older and more limited browsers benefit as well. In fact, the new site looks only marginally worse with CSS disabled entirely:

This site with CSS completely disabled

The acid test of old browsers is NCSA Mosaic. I doubt anyone still uses it for anything more than historical curiosity, but it's nice to see my site render fine on a roughly 30 year old browser:

This site works OK in NCSA Mosaic

Compromises

I doubt that deferring color decisions to browsers' default stylesheets is going to catch on. Maybe I'll eventually decide to choose my own colors (perhaps from the EGA palette, this time). Relying on default colors and transparency might introduce issues with low contrast.

I also opted to switch the tag list from a semantic list into just a bunch of links separated by "|" characters. I'm sure this is suboptimal from a semantic web (and perhaps accessibility) perspective, but I didn't see a simple and obvious solution to collapse the list onto a few lines in text-mode browsers without this sacrifice.

Regardless, if you notice any egregious problems, send me an email.

Conclusion

Is this a good idea? I think keeping sites simple is a good idea, but optimizing for rarely used browsers is, at best, probably not a good use of time. Additionally, fiddling with CSS feels a bit silly when most readers would best be served using their browser's reader mode anyway.

But the great part of having a personal web site on The Indie Web is that you can do crazy experiments like this. I hope you enjoy my creation.

If you like this theme, possibly because you have analysis paralysis around color schemes, I will be integrating it directly into the luasmith static site generator (the code is in the repository, but I haven't cut a new release yet). Feel free to copy any portion of the design.

Credit

While brainstorming new ideas and tweaks, I was inspired by the design of the following sites:

This page is copied from the blog of Jared Krinke, the creator of Luasmith

Today, I unveil my most gratuitous static site generator yet: luasmith.

It's 450 KB (static binary, including templates for this site, gzip compressed)
It builds my ~140 page site in 300 ms (wall clock time, on an 11-year-old old laptop)
It performs acceptably on a 28-year-old laptop, running NetBSD (Pentium 166 MHz)
It's trivial to compile, requiring only a C compiler, GNU Make, sed, and sh
Despite the small size, it still includes syntax highlighting for ~150 languages and internal link-checking

Show me the code!

It's like Metalsmith in Lua. See the tutorial for more, but here's an example that converts Markdown to HTML and adds the page's title to the resulting HTML:

-- Minimal HTML template (used below)
local outer = [[
<html>
  <head><title><%= title %></title></head>
  <body><%- content %></body>
</html>
]]

-- Read content/*.md, convert to HTML,
-- apply template, write to out/*.html
return {
  readFromSource("content"),
  processMarkdown(),
  applyTemplates({ { "%.html$", outer } }),
  writeToDestination("out"),
}

Note: templates use a Lua-native templating language called etlua and file matching uses Lua patterns.

Motivation

Obviously, the world does not need another static site generator. So how did I end up here?

In a word, my motivation was: simplicity. I wanted an SSG that was:

Simple to understand
Simple to bootstrap
Simple to maintain
Simple to deploy

Implementation

Here's my take on the goals above.

Simple to understand

First, I wanted the architecture to be simple, both in design and use:

The build pipeline is just a Lua script (similar to Metalsmith)
Page templates are constructed using Lua (via etlua)
Metadata on items can be specified in frontmatter using Lua (or a subset of YAML)
Relative links between Markdown files "just work" and are checked at build time (including links to headings)

Instead of creating a bespoke domain-specific language for defining the structure of a generated site or its templates, you just write some Lua code that glues together a few processing nodes and then supply templates that also use Lua (e.g. for iteration).

Overall, I'd describe the architecture as "minimalist Metalsmith in Lua, with zero runtime dependencies".

Simple to bootstrap

Given my musings about future-proof programming languages, it's obvious that I'd like to be able to compile and use my software in the future. That is easier said than done! The problem is that identifying languages that will stick around is hard. Twenty years ago, Perl might have been a reasonable choice for an SSG, but today I don't even remember how to install Perl modules.

The (previous) best static site generator ever made is built on TypeScript/JavaScript and Deno. As much as I like Deno, I'm not confident it will be maintained decades down the road. Given that I'll never know how to get it running on an i586 computer, I have doubts I'd be able to get it running on potential future architectures (RISC-V?) either.

To avoid these headaches, I went with the lowest common denominator: C. It's not convenient, it's not modern, but C works everywhere and I'm certain C will persist (for better or worse).

Aside: ideally, I'd be writing as much native code in Rust as possible, to ensure memory safety. Unfortunately, Rust's modern approach is at odds with my desire for simplicity. The toolchain is huge, the dependency trees are large, and the language is vast. Rust definitely looks like the future of robust low-level software, but for cozy side projects, I prefer being a simpleton living in the past.

Simple to maintain

One frustration I have with the JavaScript ecosystem is that it's constantly changing. Node, Deno, and Bun do a respectable job of keeping old versions around, but I don't want to have to worry about breaking changes.

On the other hand, C changes very slowly, and previous versions of Lua are essentially set in stone. Throw in some static linking, and you've even got an artifact that should stay usable for a long time.

I've also minimized the number of (vendored, compile-time) dependencies involved. Here's the full list:

md4c for converting Markdown to HTML
Lua for metadata, scripting, etc.
etlua for templates
Scintillua for syntax highlighting
LPeg to support Scintillua

You'll note that these libraries are doing all of the heavy lifting. I've basically only written glue code, an entry point, and some infrastructure. And most of the code I wrote is in Lua (which is much easier to write than C--and fast enough for all but the innermost loops).

Simple to deploy

Static binaries are wonderful. Tiny static binaries are even wonderful-er. Just copy over a tiny zip file, unzip it, and you're done. Need I say more?

Downsides

Of course, there are downsides to the approach I took:

Writing C code is fraught with peril -- fortunately, the hardest parts were mostly already done by the md4c and Lua authors
Syntax highlighting is not simple -- good news: Scintillua already solved this problem for me!
The security model of an SSG that uses Lua scripts for everything is... not ideal -- only use templates you trust!

Additionally, I haven't taken the time to set up a proper development and debugging environment for C and Lua. I need to investigate static analysis and debugging tools for Lua, as well as find a tolerable frontend for GDB. This is where I really miss Emacs+SLIME for Common Lisp or VS Code for TypeScript/Python.

Future areas of exploration

Now that I've got a static site generator running on a vintage laptop with NetBSD, where am I headed next? I'm not exactly sure, but some ideas follow.

Designing for the text-mode web

At some point, I'd like to redesign my site using an even more minimal theme. In fact, I'd like to optimize my site for text mode browsers like lynx and w3m. Why? Because I like using w3m and I want my site to be easy to use within w3m. Or maybe it's because I hate how bloated modern web browsers have become.

Further simplifying distribution

Distributing native code necessarily requires per-platform packages. Or does it? Can I package and release this minimal static site generator as a multi-OS polyglot binary using Cosmopolitan libc? Update: this now exists, but sadly, it is 64-bit only.

Simplifying the entire system

I'd like to see if I can bootstrap my entire web site's workflow from Oasis Linux (a small, statically linked, Linux-based operating system that is simple, but capable). Oasis sounds like a modern system that a single person can wrap their head around (minus the Linux kernel--though perhaps a simpler kernel could be substituted in the future?).

Blogging on vintage computers

I'm curious how far back I can go as far as vintage computing and still be able to build a static site. Can I build my SSG on Windows 98? DOS? Amiga? Inquiring minds want to know!

Conclusion

Creating a non-bloated Markdown-based static site generator has been a bucket list item for me--and now it's done!

Beyond personal goals, I found C+Lua to be a comfortable combination for side projects. This came as a surprise! Lua isn't my favorite language to write (though it's certainly much simpler to wield than C). Having said that, it's a beautifully simple language that's easy to integrate. Despite being primarily driven to Lua by my goal of building a small (in binary size) tool, Lua's minimalist take on a mostly-normal-looking scripting language won me over because I could literally pick it up and be productive within an hour or two.

With that out of the way, I should probably attend to hobbies other than static site generator performance art. Until next time!

Resources

Note: the example repository contains a simple self-contained luasmith pipeline for generating its README file.

Schemescape | Nara

Optimizing for text-mode browsers

Issues with the old design

Fixes

Header

Article list

Syntax highlighting

Dark mode

Bonus benefits

Compromises

Conclusion

Credit

A 450 KB static site generator based on Markdown and Lua

A 450 KB static site generator based on Markdown and Lua

Show me the code!

Motivation

Implementation

Simple to understand

Simple to bootstrap

Simple to maintain

Simple to deploy

Downsides

Future areas of exploration

Designing for the text-mode web

Further simplifying distribution

Simplifying the entire system

Blogging on vintage computers

Conclusion

Resources