HTML Formatter

HTML is famously forgiving of whitespace — the browser collapses runs of spaces and newlines into a single space when rendering — which means messy, unindented HTML renders correctly but becomes painful to read and maintain. A formatter restores the visual structure: one element per line, children indented under parents, so the document's hierarchy is visible at a glance.

The payoff is in debugging and review. A missing closing tag is invisible in a 200-line wall of minified markup but jumps out when every element sits at its indent level. Diffs become meaningful: a formatter normalizes whitespace first, so a git diff shows the tag you actually moved, not the indentation changes it caused.

The convention is two spaces per level (four is common too; tabs are legal but mix badly in teams), applied per nesting depth: the <html> element at zero, <head> and <body> at one, their children at two. Text nodes are treated carefully — indentation added between words in a paragraph would create visible whitespace in the rendered page, so formatters either keep text on its own line with no extra indentation or trim and re-indent deliberately.

One-attribute-per-line kicks in when a tag exceeds a width threshold (often 80 characters), keeping long attribute lists readable. Closing tags align with their opening tag's indentation. The rules are simple enough that teams rarely argue about them — which is precisely why automation beats hand-formatting: consistency comes free.

Block elements (div, p, section, headings) start on a new line and take the full available width; inline elements (span, a, strong, em) flow within text and only occupy their content's width. Formatters treat them differently: block elements each get their own line with their children nested beneath, while inline elements stay on the same line as their text and neighbouring inline elements.

Getting this wrong has consequences. Indenting an inline <span> on its own line inserts whitespace between the words around it — visible as an extra space in the rendered output, and in the middle of a word-wrapped sentence it can push text onto a new line. That's why the formatter's inline handling isn't cosmetic: it preserves the rendered output byte-for-byte while still improving readability.

The recurring errors are indentation without structure (making invalid markup look tidy), wrapping inline elements across lines (creating phantom whitespace), and adding whitespace inside <pre> or elements with white-space: pre, where spaces are significant. Hand-formatting tables or lists is also error-prone: one missed level in a nested list silently changes the document's meaning, since indentation is semantic in lists even though it's cosmetic elsewhere.

Another trap is formatting markup inside <script> and <style> blocks as if it were content — whitespace there matters to the embedded language's parser, not the HTML one. A good formatter recognizes these contexts and leaves their internal whitespace alone, only normalizing the tags around them.

Formatting and validation are complementary: a formatter normalizes presentation so you can see structure; a validator checks that the structure itself is legal — tags properly nested, void elements not closed, attributes quoted. Well-formatted HTML is far easier to audit for accessibility, because the element hierarchy is exactly the one assistive technology walks.

Clean markup also correlates with accessible markup: unclosed tags and sloppy nesting are where duplicate IDs and malformed ARIA attributes hide, and a formatter that surfaces odd nesting gives you the chance to catch an unlabeled button or a heading-out-of-order before it ships. Indentation is a small thing, but it's the difference between reading your markup and merely surviving it.