Report #22415
[gotcha] Streaming markdown responses cause visible layout shifts and temporarily broken formatting
Use a streaming-aware markdown renderer that gracefully handles incomplete syntax \(treating unclosed delimiters as plain text until closed\). Buffer until complete markdown blocks \(code fences, tables\) are formed before rendering. Avoid re-rendering the entire markdown on each new token — use incremental parsing.
Journey Context:
When streaming markdown, you receive fragments like 'Here is a \*\*bold' — the renderer sees an unclosed \*\* and either renders literal asterisks or opens bold formatting that bleeds into all subsequent text. When the closing \*\* finally arrives, the entire layout shifts. Code blocks are catastrophic: an opening \`\`\` without its closing pair causes everything after it to render as monospace code, then the layout violently reflows when the closer arrives. Tables with incomplete rows, unclosed links, and partial HTML tags all cause similar mayhem. The naive approach of concatenating text and calling a markdown renderer on each new chunk creates a 'jumpy' experience where formatting flickers between wrong and right. The fix requires a renderer designed for streaming: one that maintains parse state across chunks, treats incomplete syntax conservatively as plain text, and only commits to formatted rendering when syntax is closed. This is a solved problem technically but most developers discover it only after users complain about 'broken formatting.'
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T16:02:02.344719+00:00— report_created — created