Welcome to this very basic example of a web page. It has two main goals:
Let's start with the formal definition of literate programming:
“ Literate programming is when the programmer writes the documentation for the code in the same file as the code itself. This is in contrast to traditional programming, where the documentation is written in a separate file. ”
In plain English, it means you write the code and the help text that explains it all in the same document, so you don't have to switch between multiple files to understand what's going on.
For an HTML page like this one, that documentation is in the form of a bunch of comments in the HTML that explains how it works. If you're on a laptop or desktop computer, you can use the "view source" feature of your browser to see these comments that I've sprinkled throughout the markup.
If you're on mobile instead then don't sweat it, I made this special version of the page that simulates what you'd see elsewhere.
I wrote a metric ton of comments in the HTML of this page. Almost a crazy amount, to be frank, like I was writing a novel about the adventures of Mr Markup and Mrs Browser. The goal of writing so much was to make everything self-explanatory, even if you've never seen the source of a web page before.
This page also exists as a small demonstration of why I can never fully participate in CSS Naked Day, a fun annual event where people strip away the CSS from their websites for a day to celebrate the beauty of plain text and unstyled HTML.
That might sound surprising if you read the section above, and really surprising if you cracked open the source of this page and saw all the comments explaining every single element. Clearly I love HTML.
I'm exactly the kind of person who should love this. I might be old but hey, I like fun. I've been using HTML since before CSS had layouts. I love the minimalism and simplicity of clean markup for a host of reasons. It easier to write, read, and maintain; it performs like a champ on slow connections and fast alike.
Most of all, it's appealingly punk rock to strip things down to the core fundamentals and go against the grain in an era of vibe coded junk output.
However, as much as I appreciate the ideals behind going "naked" once a year, there's one big massive catch for me: I personally find plain text and unstyled HTML to be nearly unreadable on desktop.
Font sizes, line lengths, and spacing all default to settings that haven't worked since the pre-tables era of the early web. The black text on white not only starches your eyes if you're reading in the evening, but it looks like an accidental kind of broken, rather than something that's clearly intentionally simple.
It looks undesigned. Even your average code editor looks better in comparison. Why strip away the style if that's the result?
I mean come on, demonize javascript all you want. But CSS? Stylesheets are the shit.
The good news? You don't actually need a lot of CSS to fix this! With just a few lines, you can make an immense improvement in legibility and drag the page into the modern era. Minimal effort, maximum benefit.
Enough rambling. If just looking at this page hasn't convinced you yet, let's unpack the details of the formatting tweaks.
There's only so long a line of text can be before it becomes difficult to read. The ideal length is between 45 to 75 characters wide, with 66 the ideal. It's set to 55 here because that resulted in 66 characters wide with typical writing (i.e. not a repeating sequence of zeroes)
The best thing the iPhone ever did was to kill the trend of sidebars and annoying distractions that dominated the web in the early 2000s. Out went old timey newspaper-style layouts and in came a focused experience around a single column of text. Give your words room to breathe.
Font size, font family, and line height. The basic currency of not just readability but also the personality behind the words. I.e. design.
Why make your text look like it was pooped out by a machine? You're human, we're all different, pick what works for you.
No, not that kind of contrast like between light and dark colors. I'm talking about breaking up a column of text with the occasional blockquote, image, or other visual element.
“It’s the contrast of light and dark that each give the other one meaning.”
— Bob Ross
Even on a page where the text is the main course, it's good to mix things up a bit and change the rhythm. Otherwise it just becomes a never-ending stream of text with no visual breaks.
I love dark mode. I love it the way Jerry Seineld loves cereal: I can enjoy it 24/7, no matter the social conventions.
You don't need to have complicated media queries or create a javascript toggle to make it work. For a simple enough page like this one, you can just set it to dark mode by default. Boom, done. No more unexpected flashlight in the face like you're being interrogated by cops.
Also, a design tip: pure white designs look semi-broken from a first impression standpoint, whereas dark colors fill up a space with a subtle sense of intentionality. I should unpack that in a blog post someday, or you can join me on one of the weekly Homebrew Club Zooms if you want more color commentary (accidental pun 🤦🏻)
So, those were my two goals for this page. One around markup and the other focused on styles.
You'd be forgiven for thinking that these two goals sound like they're at odds from the way I've nitpicked the brokeness of the default settings, but they're not. They're two love letters to the letters that make up the web. One is an ode to HTML, the other to CSS. They're the peanut butter and jam of the web.
I hope you feel the same about HTML and CSS as I do, little bits of everyday magic made possible by nothing more than plain text. This polemic was just as much for me as anyone else, a reminder to step back and appreciate the building blocks of the web that we sometimes take for granted.
And if you made it this far and actually read everything, then wow. First of all, thank you. You're exactly my kind of good egg. Secondly, you might want to stay in touch, either by reading my blog or showing up to one of the many inspiring Homebrew Club zooms hosted by the IndieWeb community.