Markdown to HTML: 7 Conversions That Break in Production
Markdown looks like a solved problem: headings, bold, links, done. Then you render user content or a docs page at scale and find broken tables, literal & in URLs, code samples with curly quotes, and a link that quietly jumps to the wrong heading.
Every renderer agrees on the basics. These are the seven places where implementations diverge, with the input that causes the damage and the fix that holds.
1. Raw HTML passes through, including the parts you did not write
CommonMark and most flavors pass inline HTML straight to the output. That is how <details> blocks and embedded iframes get into docs. It is also how a support ticket becomes stored XSS.
Two payloads survive a naive renderer: <img src=x onerror=alert(1)> and a link target like [click](javascript:alert(1)). Neither is markdown syntax, so no parser-level check sees them.
Fix: sanitize the rendered HTML with a tag allowlist and a scheme allowlist (http, https, mailto, tel). Sanitizing the input instead is wrong, because markdown itself is not the attack surface, the HTML it produces is.
2. Indentation silently changes the block type
Four leading spaces mean code block. That one rule breaks more documents than any other, because nested list content sits at exactly that depth.
This renders as one list item with a continuation paragraph:
1. Install the package
then run the migration
Change those three spaces to four and the same text becomes a <pre> block, unstyled and unsearchable. Use tabs where the editor uses spaces, or mix both, and the output changes again between the browser preview and the server render.
Fix: render server-side and read the HTML source. Fix the indentation in the source, do not adjust the CSS. Nested items need indentation equal to the parent marker plus one space, so 1. needs three, 10. needs four.
3. A single newline is not a line break
Two trailing spaces force <br> in most flavors. Editors strip trailing whitespace on save, and code review tools hide it, so the break exists locally and disappears in CI.
Practical casualty: postal addresses, two-column spec tables written as plain text, and lyrics or log excerpts. All collapse into one run-on paragraph after deployment.
Fix: do not rely on trailing spaces. Use a blank line plus a list, or emit explicit <br> in the HTML stage, or enable the flavor option that treats single newlines as breaks, and then accept that every wrapped paragraph in the source now gets a break too.
4. Ampersands get escaped twice
A query string like ?page=2&sort=date must become & in HTML, which is correct. The bug is storing the escaped version and escaping again on render: the page then shows &amp; and every link with two parameters dies.
Same failure with © written without the semicolon, and with code samples containing <: they render as characters instead of showing the source.
Fix: store raw text, escape exactly once at render time, and check a page with a multi-parameter URL in the body. If you paste the output into a converter and see &, the escaping happens twice somewhere upstream.
5. Tables fail on a pipe inside a code span
Gutenberg tables split cells on | before parsing inline code. A cell like grep -E 'a|b' splits into two cells, every later column shifts right by one, and the header no longer matches the body.
The second classic is the delimiter row: it needs at least three dashes per column. Two dashes and the whole table renders as a paragraph of pipes.
Fix: escape in-cell pipes with a leading backslash, keep delimiter rows at ---, and render one table with an escaped pipe before trusting the pipeline.
6. Smart quotes mangle code samples
Typographer-style post-processing converts straight quotes to curly ones, double hyphens to an en dash, and three dots to an ellipsis. Fenced code blocks are usually excluded. Inline code often is not.
The damage is invisible in a browser and expensive in practice: a JSON sample with curly quotes cannot be copy-pasted into a terminal, and a CLI flag with a converted dash returns unknown option.
Fix: disable typographic replacement for anything inside code, or run the renderer first and the typographer only on text nodes. Test with a JSON snippet and a command that has a double-dash flag.
7. Heading anchors collide or vanish
Two sections called ## Notes get the same generated id, so the second table-of-contents entry jumps to the first heading. Non-Latin headings slugify to an empty string in several implementations, leaving an empty id attribute and a dead anchor. A heading that starts with a number or an emoji fails in a third set of renderers.
Fix: append a counter on collision, transliterate or hash non-ASCII headings, and verify anchors on the rendered page instead of the source. If you publish docs in several languages, pin the anchor in the source rather than letting each renderer invent one.
A five-minute check before shipping
- Render a sample with raw HTML, a table containing a pipe, a nested ordered list, and a code block with quotes and double-dash flags.
- Open the HTML source, not the preview. Look for
<pre>where a paragraph should be, and for&in hrefs. - Run the same sample through the Markdown to HTML converter and compare with your server output. A difference means your pipeline adds a step nobody documented.
- Take a live page back through HTML to Markdown and compare the round trip with the original source using a diff. Losses show up as changed whitespace and dropped anchors.
- Clean copy pasted from a CMS or a chat window with the Markdown cleaner before it reaches the repo: hidden zero-width characters and non-breaking spaces break indentation rules silently.
None of this needs a new library. It needs one rendered sample per edge case and a diff against the previous deploy. Most markdown bugs are not parser bugs at all, they are the two or three post-processing steps a framework adds around the parser. An entity converter tells you quickly whether an escaping layer is doing something you did not ask for.