HTML Escaping

Markdown's output is HTML, and its input is whatever a user typed. Somewhere between those two facts sits every Markdown-powered security incident ever filed. Your program will escape a whole document for HTML output, copying well-formed entity references through unchanged.

Which characters have to change?

The reference renderer escapes all four everywhere, so this course does too: a quote in a paragraph and a quote in an attribute take the same path, and the escaper never needs to know which one it is in.

Escaping is a render-time job, not a parse-time one. You escape when you write a character into the HTML output, which means the contents of code spans and code blocks get escaped too. A <script> tag inside backticks must display as text, not execute.

Why is the ampersand the hard one?

Because it is the one character whose replacement contains itself, and because authors legitimately write entity references by hand. Replace blindly and you escape your own escapes:

Rows two and three are the bug: an author who already wrote an entity gets it mangled into visible & noise. The fix is a lookahead. Before escaping an ampersand, check whether it begins a well-formed entity reference, and if so copy the whole reference through untouched.

What counts as an entity?

CommonMark recognises three shapes:

Anything else, such as &&, & c, an unterminated &amp, &#;, &D; (too short) or an eight-digit number, is a bare ampersand and gets escaped normally. The real parser also checks a named entity against the HTML5 list of about two thousand names, so &madeup; is escaped; this exercise checks only the shape and leaves the table out.

Escape order

If you escape with a chain of replacements instead of one scan, & must go first. Escape < first and its replacement's own ampersand gets caught by the later pass, turning < into <. A single left-to-right scan that handles each character once avoids the question entirely, and it is the only approach that can also protect entities.

Is escaping enough to be safe?

No. CommonMark deliberately permits raw HTML, so a conforming parser will happily pass <script> straight through when it appears at block level. Several widely used Markdown libraries have shipped cross-site-scripting advisories over the years for exactly this reason. For untrusted input, render with raw HTML disabled if your library supports it, and run the resulting HTML through a dedicated sanitizer regardless. The raw-HTML lesson comes back to this.

Common mistakes

• Double-escaping a valid entity. Already & escaped must come back unchanged. A plain replace("&", "&") returns &.
• Only recognising the named shape. A and A are entities too.
• Working line by line. The input is a whole document; copy every newline (including a CR) through like any other character so nothing is added or lost.
• Forgetting the quote. " becomes " as well.

Your exercise

Escape a document, entity-aware. The starter reads all of stdin as one string and writes your result back unchanged; you write entity_length (the three shapes above) and escape (one scan, one decision per character).