Soenneker.Html.Normalizer 11.0.127

Soenneker.Html.Normalizer

Deterministic, configurable HTML normalization for hashing and change detection.

Installation

dotnet add package Soenneker.Html.Normalizer
```bash

## Usage

```csharp
using Soenneker.Html.Normalizer.Models;

HtmlNormalizationResult result = await normalizer.NormalizeAndHash(renderedHtml);

Console.WriteLine(result.Html);
Console.WriteLine(result.Hash);

The default profile removes common runtime artifacts while preserving indexable content:

• HTML comments
• <style> elements
• scripts other than application/ld+json
• nonce attributes
• Blazor _bl_* element-reference attributes
• element IDs and common HTML/ARIA attributes that reference them
• formatting-only inter-element whitespace

It also normalizes line endings and sorts ordinary HTML attributes. Hashing uses XXH3 through Soenneker.Hashing.XxHash, producing a lowercase 64-bit hexadecimal hash for fast, non-adversarial change detection.

Application-specific normalization

using System.Text.RegularExpressions;
using Soenneker.Html.Normalizer.Options;

var options = new HtmlNormalizationOptions();

options.RemoveSelectors.Add("[data-runtime-only]");
options.RemoveAttributes.Add("data-request-id");
options.Replacements.Add(new HtmlNormalizationReplacement(
    "session-[a-f0-9]{32}",
    "session-id",
    RegexOptions.IgnoreCase | RegexOptions.CultureInvariant));

string normalized = await normalizer.Normalize(renderedHtml, options);

Dependency injection

using Soenneker.Html.Normalizer.Registrars;

services.AddHtmlNormalizerAsSingleton();
// or services.AddHtmlNormalizerAsScoped();

Browser readiness is intentionally outside this package. Wait for hydration or another application-specific readiness signal before capturing and normalizing rendered HTML.

Normalized output is for comparison, not for rendering back to users: the default profile removes IDs and ID-reference attributes that can be functionally or accessibility significant. Disable the corresponding options when those values are part of the change you need to detect.

String-based replacements use a one-second regex match timeout. When supplying an existing Regex, construct it with an appropriate timeout yourself. XXH3 is a fast non-cryptographic hash; do not use it for signatures, password storage, or authenticity checks.