Compare HTML Files and Detect Markup Changes

HTML Diff Comparison

Comparing HTML files is challenging because the same rendered output can be represented by different markup. Whitespace differences, attribute order, and self-closing tag styles can all produce textual diffs that are visually meaningless.

Challenges of HTML Diffing

<!-- Version A -->
<img src="logo.png" alt="Logo" class="header-img" />

<!-- Version B -->
<img class="header-img" src="logo.png" alt="Logo">

These two lines are functionally identical, but a plain text diff marks them as completely different. Smart HTML diff needs to normalize the markup before comparing.

Normalization Strategies

Before diffing, normalize both HTML inputs:

1. Format consistently — apply the same indentation and line breaks
2. Sort attributes — put attributes in alphabetical order
3. Normalize quotes — convert all attribute values to double quotes
4. Normalize self-closing tags — choose one style (<br> or <br />)
5. Trim whitespace — remove extra spaces within tags

Types of HTML Changes

Change Type	Example
Tag added	New <section> block inserted
Tag removed	<div class="deprecated"> deleted
Attribute changed	class="old" → class="new"
Attribute added	data-testid="btn" added
Content changed	Inner text modified
Structure changed	Element moved to different parent

Comparing Rendered Output

For template or component changes, sometimes you want to compare the rendered HTML output rather than the source:

# Generate HTML from templates, then diff
diff <(curl -s localhost:3000/old) <(curl -s localhost:3000/new)

Semantic vs. Textual Diff

A semantic HTML diff understands the DOM tree:

• Moved elements are shown as "moved" rather than "deleted + added"
• Attribute-only changes are separated from content changes
• Whitespace-only differences can be filtered out

Best Practices

• Always format/prettify both HTML files before diffing
• Use a diff tool that understands HTML structure
• Focus on attribute and content changes, not whitespace