Skip to main content
BuildLogicStudio
Begin
Index / Journal / Why we still write our HTML by hand

Why we still write our HTML by hand

A short essay on the trade-off that nobody at the studio has ever regretted: writing the markup yourself, in a real editor, with semantic tags, before any framework or generator has touched it.

W Why we still write our HTML by hand

There is a tendency in our part of the industry to assume that hand-written HTML is a relic. The frameworks have won, the argument goes, and only a stubborn minority still write semantic markup before generating it. The frameworks have not won. They have grown louder, which is a different thing, and the studios that still write HTML by hand have grown quieter, which is also a different thing.

The practical case for hand-written markup is short and unromantic. Every framework adds an indirection between the structure you describe and the structure that actually reaches the browser. The indirection is sometimes useful — for an application with seven hundred routes and a complicated state graph, the indirection is necessary — but for the marketing site of a forty-person company, the indirection is a tax. The tax is paid in megabytes of JavaScript, in build complexity, in the small daily cost of explaining to a junior developer why the rendered HTML does not match the source they were reading.

The aesthetic case is longer and more contentious. Hand-written markup forces a kind of slowness on the engineer. You see every tag. You see every nested element. You think about whether a paragraph wants to be a paragraph, whether a list wants to be a list, whether the heading structure tells the story the page is supposed to tell. A framework that produces markup for you produces it correctly often enough that you stop checking. After a few years of not checking, you forget what you are checking for.

There is a third case, which is the one we make to clients when they ask. A hand-written site is a site that can be edited two years from now by someone who is not in the studio anymore. The CSS is in two files. The JavaScript is in one file, and there are three hundred lines of it. The HTML is read from top to bottom and reads like an article. We have inherited fifteen-year-old sites that were hand-written and could still be edited in a single afternoon. We have inherited three-year-old framework projects that nobody can deploy because the build chain has rotted.

None of this is an argument against the frameworks themselves. Two of the four people in the studio used React for many years before this and one of them still does, on the application halves of Atelier Builds. The argument is for a smaller habit: write the marketing site by hand. Reach for the framework when the page actually needs the framework. Most pages do not. Most pages, even today, are paragraphs and lists and the occasional form, and a single competent engineer can write them out in a morning, and the result will outlive the engineer.

The studio quiet rule is that no page on a marketing site ships with more than one-hundred-fifty kilobytes of JavaScript on the first load. That is not because we are puritans about it; it is because the budget is a forcing function. If you cannot fit the marketing site into one-hundred-fifty kilobytes, you have written the marketing site wrong. The budget makes the right thing easy and the wrong thing visible, which is more or less the only thing a constraint is for.

Have a project that needs this kind of attention?

Write to us. The engineer who replies is the engineer who would run the engagement.