HTML Escaping Done Right

Why HTML needs escaping at all

HTML uses a handful of characters as its own grammar: angle brackets delimit tags, ampersands open entities, quotes delimit attributes. When those characters appear as content, the parser must be told they are content — and entities are that instruction. Without encoding, a less-than sign in a code sample truncates everything after it as a bogus tag, and an ampersand before the wrong letters becomes a mystery entity.

The reserved set: what must always be encoded

The mandatory minimum: ampersand always (it starts every entity), less-than and greater-than in text content (they start and end tags), and quotes inside attribute values. Everything beyond that is choice — encoding more is never wrong, only less readable. The practical habit: encode the reserved set mechanically and leave ordinary text alone.

Context decides the rules

Escaping is not one operation — each HTML context has its own dangerous characters. Text content worries about angle brackets and ampersands; attribute values worry about the quote character wrapping them; JavaScript inside script blocks and URLs inside hrefs have entirely different rules. The classic XSS pattern is applying text-context escaping to a JavaScript context and discovering too late that the contexts are not interchangeable. Match the encoding to where the content lands.

Named versus numeric entities

The same character has two spellings: a named form (readable but covering a limited catalog) and a numeric form (universal, covering every Unicode code point). Modern practice favors named entities for the common cases because they read well in source, and numeric references when the character has no name or the transport demands pure ASCII. Both decode identically in browsers.

Non-ASCII: when you can just not encode

The historical rule — encode every non-ASCII character — came from ASCII-only transports. Modern UTF-8 documents carry accents, emoji, and non-Latin scripts directly, and should: raw characters keep source readable and diffable. The remaining cases for numeric encoding: documents with non-UTF-8 declarations, formats that strip high bytes, and environments where the character would be misinterpreted. Encode by constraint, not by habit.

The XSS connection: encoding as defense

Cross-site scripting succeeds when attacker-supplied text reaches the page as markup or script instead of data. Output encoding — converting that text's special characters to entities at render time — is the primary defense for HTML contexts. Every framework's auto-escaping exists to do this by default. Understanding entities is understanding what that defense actually does: it makes dangerous characters display instead of execute.

Decoding: reading entity-laden source

The reverse job appears constantly: page sources, CMS exports, and API responses full of entities that need to become readable text again. Decoding resolves named and numeric forms back to characters. The recurring nuisance is double encoding — content escaped twice — which decodes one layer at a time. If decoded text still contains ampersand-something-semicolon, decode again.

Copy-paste corruption and its cure

Text copied between systems often arrives with its special characters already entity-encoded, or with smart quotes and non-breaking spaces mixed into plain content. A decode pass normalizes the first problem; the text cleaner handles the second. The combination restores any mangled paste to clean editable text in seconds.

Testing what your markup actually needs

The empirical check beats memorization: paste the content encoded, render it, and confirm display. Code samples are the canonical test case — they contain every reserved character routinely. Building one properly escaped code block teaches the rules more durably than any reference table.

Local conversion for user content

The text being escaped is frequently user-generated — comments, reviews, form submissions — which makes it exactly the content that should not travel to third-party services for processing. Local conversion keeps the sanitization workflow on your machine.

Named versus numeric entities: choosing the reference

Most characters with entities have two spellings — a named form (amp, lt, copy) and numeric forms (decimal #38 or hex #x26 for the same ampersand). Named entities read better but only a defined roster exists; numeric references cover every Unicode code point, so characters without names have no alternative. Compatibility also differs subtly: the oldest parsers recognized only the first entity set, which is why email templates still favor numeric for exotic characters. The practical rule: named entities for the common five in HTML text, numeric references for everything else, and consistency within any single document.

Where escaping is mandatory and where it is optional

Mandatory: less-than and ampersand in text content (they begin markup), quotes inside attribute values of the same quote style, and any character the declared encoding cannot represent. Everything else — including accented characters in UTF-8 documents — can stay literal. Over-escaping is not harmless: fully-escaped text resists search and translation tooling, and inflates size. The quality bar is minimal correct escaping: the mandatory set plus whatever the transport genuinely threatens. Conversion tools that escape everything are safe but produce text humans struggle to read, which matters when the output gets edited later.

Decoding entities from scraped and mangled content

The reverse direction fixes a recurring mess: content saved with entities intact but rendered contexts that show them literally — visible amp-semicolon sequences in titles, exported feeds with double-escaped sequences (the entity for ampersand followed by 'amp;'). Decoding restores the characters, and double-encoded sequences need two passes. The diagnostic tell for double-encoding is the literal word 'amp' near broken characters. Scraping pipelines should decode once at extraction time and never re-encode except at final output, because each extra pass through encode-decode cycles is another opportunity for corruption.

Entities, escapes, and the five that matter

HTML parsing has exactly five characters that must be escaped in text content and attribute values: < and > because they open tags, & because it opens entities, and the quote characters " and ' because they delimit attributes. Every other entity — ©, —, ♥ — is a readability choice, not a correctness requirement, because UTF-8 can carry those symbols directly. The practical rule: escape the five structural characters mechanically, and write everything else as literal Unicode, which is what modern tooling expects and what survives copy-paste into non-HTML contexts.

The conversion direction matters. Turning literal text into escaped HTML is what you do before embedding user input in a template — it is the defense against markup injection. Turning entities back into text is what you do when a feed or export delivered content already escaped and you need the real characters, typically before placing the text somewhere that escapes again. That second case is where double-encoding happens: converting & to &, then passing the result through another escaper that turns it back, leaves the user staring at the entity name instead of the character.

Numeric references deserve one note: © and © are the same character, and both are valid. Numeric form is the safer interchange format because it depends on nothing but the code point — no named-entity table, no HTML version. When you generate markup programmatically for an unknown consumer, emit numeric escapes for the five structural characters and literal Unicode for the rest.

Common mistakes with this tool

• Applying HTML-text escaping inside attributes or script contexts.
• Double-encoding content and wondering why entities survive decoding.
• Encoding every non-ASCII character in a UTF-8 document out of habit.
• Skipping escape testing on content that contains code samples.

Frequently asked questions