If you’re reading this, you are reading a web page generated by a static site generator I built. Before this, I used Hugo and then Zola. Both are great at what they do, but they had a lot of features I didn’t need and some features I wanted that they didn’t have. One of the key features I really wanted was the ability to format the HTML code generated by the static site generator.
Now when I say “formatting HTML code”, I mean formatting the markup that a visitor sees when they use the “View Page Source” feature of their browser and not necessarily the source code we author directly, although that goes without saying.
In previous iterations of this site, I used HTML Tidy to format the HTML code. However, it started choking on attributes intended for XHTML (even though it is on an HTML 5 document) I was using, thus leaving the HTML code unformatted. I should have removed those custom attributes, but I figured the formatting needed to be done even when the HTML code was invalid. And so I implemented my own1. 🤦♂️
There is no valid justification for not reusing an existing HTML formatter aside from my very specific, but arguably unimportant, requirements. Instead, I want to articulate why I wanted to format the HTML code on this website in the first place.
A Case for Formatting HTML Code
Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. —Donald Knuth, Literate Programming
Wiser people have already talked about this, but often in the context of writing computer programs. I believe many of these ideas, on many levels, also apply to writing markup code –that we should format HTML for human beings.
As people who make websites, we have been conditioned to write markup optimized for browser consumption. We mangle our code with minification tools to make them load faster. We may at least format them on the authorship side for ourselves and for the people who work with us, but then leave the final (un)formatting to the tools when they’re served to the browser.
Google thinks this source is not for you to read, curious one.
Who would view the raw HTML code on my website anyway? What kind of human are they? I imagine that at least some of them are like how I was when I was still learning to build webpages.
One of the OGs out there.
I started learning how to build websites when HTML 4 was the latest HTML version and XHTML was the trendiest thing. There were no browser-based developer tools then and the only way to see the HTML code of a web page was to use the “View Page Source” feature of the browser. Back then, you could find all sorts of HTML formatting.
Many had no discernable formatting at all, probably because of the nature of the available tools at the time. But some had some semblance of structure because they “hand-crafted” the HTML code using a basic text editor like Notepad. They were formatting it for themselves!
That had the neat effect of making the source code more readable to other people, especially curious visitors. Some may have been curious for the wrong reasons, but some, I imagine, were like me just trying to learn how things work.
There are arguably better ways to view the HTML code of a web page. There are the browsers’ developer tools that provide a parsed and easily navigable view of the HTML tree. Why then bother formatting the raw HTML code that maybe a rare kind of visitor might see?
This is the Campfire
I believe, like others do, that more people should build websites. If we are to claw back some control of our online spaces from corporations and shareholders who do not have our best interest in mind, then we must encourage more people to help build those spaces. One of the few things we could do is remove some of the barriers that discourage people from building websites. I think it’s only right that we make their journey to this side of the web less hostile.
Making webpages’ HTML code more readable takes out some of the mystery of how web pages are built. To a person starting out trying to build websites, a well-formatted code could be a revelation, an invitation to look around and explore.
I’d also like to think of the HTML source as one of the few places where we can commune with other humans who build websites. If you’ve seen funny or interesting comments on HTML sources before, you’ll know what I mean.
People leave some interesting messages in their HTML source code.
On those HTML comments we find all kinds of notes, from design decisions, technical difficulties, hiring invitations, to straight up cryptic announcements. As more and more websites are built using mechanical frameworks and sterile markup, it’s refreshing to see glimpses of humanity in some rare websites.
Show Them What You’re Made Of
If you haven’t done it yet, you should build your own website. Beyond self-promotion, portfolios, and personal branding, you should share your voice and unique perspective outside the walled gardens of corporate tech platforms.
And when you do, if you are able, format your HTML. There are free and online tools to choose from out there. If you know your way around your authoring tools, you could incorporate formatting tools like HTML Tidy, prettier and js-beautify. Some solutions exist for publishing and authoring platforms like WordPress but I sincerely hope that these platforms include HTML formatting as a feature you can easily opt into. However you can, do it. Do it for the humans.
-
I forked a project but the code had become so unrecognizable and probably horrible to the ones who first wrote it that it’s basically different. ↩︎