the case for manual formatting

I care about writing good, correct code so when tools like Prettier refuse to output spec-compliant code, I get quite annoyed. Especially when the resource I point all new web developers to for learning HTML, MDN, has incorrect code scattered all over it as a result. If you want to know more, I recommend Jake Archibald's article against self-closing tags in HTML.

It was this irritation that drove me to go on a wild hunt to explore my options. The first solution I found was the prettier-plugin-void-html plugin. At the time, this had a game-breaking bug (the fixing of which is my proud second contribution to open source), so I kept looking. Next I found dprint, a highly configurable formatter, but, even after the long-suffering maintainer of the HTML plugin made changes based on my feedback, it still didn't quite feel right.

What I'd discovered is that I care a little too much about the presentation of my code to allow someone else's formatting rules to run rampant. I disabled all automatic formatting and felt the wind rush through my hair as I ran, free of other's nonsense, through the meadows.

Well, actually I only did that on this website. This site is crafted artisanally with no SSG, SSR, bundling, minification, templating or build step of any kind. I do it this way because it's more fun, so it made sense to trial my newfound, carefree existence here. I say this as a disclaimer that formatters actually are good, essential even, if you're working on a team.

Soon after I made the transition to manual formatting, a post by Aaron Parks crossed my path for the second time. Back in 2022, he told us all to Write HTML Right and, while at the the time I didn't agree with what he said, it stuck with me. His essential point is that the HTML Standard allows us to write significantly less code than we currently do and still get the same output.

In the web development world, it's usually the third party tools like SASS or Handlebars that allow us to reduce the code we right by abstraction. You can imagine my joy, then, to discover I could reduce my code footprint, and improve my readability, using spec-only HTML!

In practice, this means that I remove the head and body tags, and the closing tags of p, li and html (I leave the opening tag so I can add the language code). So, my pages go from this: 

<!doctype html>
<html lang="en-GB">
  <head>
    <title>felix waller</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="alternate" href="/rss.xml" type="application/rss+xml" title="felix waller">
    <link rel="stylesheet" href="/base.css">
  </head>
  <body>
    <main>
      <h1>the case for manual formatting</h1>
      <p>
        I care about writing good, correct code so when tools like <a
        href="https://github.com/prettier/prettier/issues/15336">Prettier
        refuse to output spec-compliant code</a>, I get
        quite annoyed. Especially when the resource I
        point all new web developers to for learning HTML,
        <a href="https://developer.mozilla.org">MDN</a>, has
        incorrect code scattered all over it as a result. If you
        want to know more, I recommend Jake Archibald's article <a
        href="https://jakearchibald.com/2023/against-self-closing-tags-in-html">against
        self-closing tags in HTML</a>.
      </p>
      <p>
        It was this irritation that drove me to go on a wild hunt to explore my options.

to this: 

<!doctype html>
<html lang=en-gb>

<title>felix waller is thinking can you balance explicit and concise</title>
<meta charset=utf-8>
<meta name=viewport content="width=device-width, initial-scale=1">
<link rel=alternate href=/rss.xml type=application/rss+xml title="felix waller">
<link rel=stylesheet href=/base.css>

<main>
  <h1>the case for manual formatting</h1>
  <p>
    I care about writing good, correct code so when tools like <a href=https://github.com/prettier/prettier/issues/15336>Prettier refuse to output spec-compliant code</a>, I get quite annoyed.
    Especially when the resource I point all new web developers to for learning HTML, <a href=https://developer.mozilla.org>MDN</a>, has incorrect code scattered all over it as a result.
    If you want to know more, I recommend Jake Archibald's article <a href=https://jakearchibald.com/2023/against-self-closing-tags-in-html>against self-closing tags in HTML</a>.
  <p>
    It was this irritation that drove me to go on a wild hunt to explore my options.

I hope we can all agree it feels nicer. Cleaner. We've removed a lot of the noise and kept only the most essential parts of the document, reducing indentation as a nice side effect. I've also dropped quoted attributes wherever possible, again in the pursuit of cleanliness.

This looks unlike the HTML we all learn, but all it takes is memorising the list of optional tags in their contexts and the list of disallowed characters in unquoted attributes. The first is easy to intuit and can be tested just by peeking at the DOM. For the second you can use the unquoted attribute value validator.

It took ditching the last of the build-step-like tools, the formatter, for me to finally unlock the full potential of HTML. I thoroughly recommend you experiment with it too.