html-to-markdown

What html-to-markdown actually does

Converting HTML to Markdown looks like tag substitution and is mostly an escaping problem, because the two languages disagree about where markup stops. Two cases account for most of the damage. The first is a code block. HTML writes a less-than sign inside a code sample as an entity, and a browser shows the reader the character. Markdown does not resolve entity references inside code spans or fenced blocks, which CommonMark states outright, so a converter that copies the entity across hands the reader the entity itself: the sample now reads with a stray ampersand-l-t in it. The characters have to be decoded on the way out precisely because Markdown will not decode them later. The second is a table. A pipe inside a cell is a cell boundary to GFM, and a row with more cells than the header has its excess discarded, so a cell containing an option list or a regular expression loses everything after the first pipe and the table still renders, looking fine. Both were live defects in this tool until 2026-08-22, along with a third: the entity decoder resolved the ampersand first, so an author who wrote an escaped entity to display an entity got a bare character instead. The results are now checked by rendering them with an independent Markdown renderer and reading what the reader would see.