How HTML minification works and when whitespace matters
HTML is harder to minify than CSS because some spaces in a document are visible text. A good HTML minifier knows which gaps the reader sees and which ones only exist to make the source tidy.
Start with the question: is this space visible?
When the browser builds a page, it collapses any run of spaces, tabs and line breaks in normal text into a single space. So ten spaces between two words look the same as one. But one space between two words, or between two links in a sentence, still shows. The minifier’s whole job is to tell those apart.
| Where the whitespace is | Safe to remove? | Why |
|---|---|---|
Between block elements such as </li> and <li> | Usually yes | Block boxes do not render the gap as text |
| Indentation at the start of lines | Collapse to one space or remove | Collapsed by the browser anyway |
Between two inline elements, such as two <a> tags in a sentence | No, keep one space | Removing it joins the words |
Inside <pre> and <textarea> | Never | These elements show every space and line break |
Between inline-block items | Changes the layout | The gap between them is a real text space |
That last row is why some layouts shift after minifying: a row of inline-block buttons loses the small gaps that the source line breaks used to create.
A worked example
This 217-byte snippet is indented for reading:
<!-- main navigation -->
<ul class="nav">
<li>
<a href="/">Home</a>
</li>
<li>
<a href="/about.html">About</a>
</li>
</ul>
<input type="checkbox" checked="checked" disabled="disabled">
A fairly aggressive minifier produces 120 bytes:
<ul class="nav"><li><a href="/">Home</a><li><a href="/about.html">About</a></ul><input type="checkbox" checked disabled>
The saving is 97 bytes, about 45% (1 − 120 ÷ 217 = 0.447). Four separate rules did the work:
- The comment went.
- Indentation and line breaks between block-level tags went.
- The closing
</li>tags went. The HTML standard lists them as optional, because the next<li>or the closing</ul>ends the item. - Boolean attributes lost their values.
checkedon its own means the same aschecked="checked".
Options you can usually turn on
- Remove comments, except ones a tool relies on, such as markers for server-side includes.
- Collapse whitespace conservatively: replace every run with a single space instead of deleting it. This is safe almost everywhere.
- Minify inline CSS and JavaScript inside
<style>and<script>, using a real CSS or JS minifier for those parts. - Remove redundant attributes, such as
type="text/javascript"on a script, which is the default.
Options to leave off unless you test
- Remove all whitespace between tags. This is the setting that joins words and moves inline-block items.
- Remove attribute quotes. It is legal for simple values, but a value with a space, an equals sign or a quote character must stay quoted. A hand edit later can easily break it.
- Remove optional tags such as
<html>,<head>and<body>. The parser adds them back, but other tools that read your HTML may not expect it.
Checklist after minifying
- Open the page and compare it side by side with the unminified version.
- Look closely at sentences that contain links, bold text or icons.
- Check any
<pre>code sample and any<textarea>default text. - Run the result through an HTML validator to catch a broken attribute.
Questions
Is HTML minification worth it on a small site?
The gain is modest when the server already compresses responses with gzip or Brotli, because compression handles repeated spaces well. It costs little in a build step, so many sites do it, but it is rarely the first speed fix to make.
Can minifying break JavaScript in the page?
It can if a tool treats script text as HTML, or if a script reads text that depends on whitespace. Use a tool that hands script contents to a proper JavaScript minifier, or leave inline scripts alone.