Troubleshooting by Symptom

Not sure what is broken yet? Start with the symptom cards below: pick what you actually see — missing styles, a diagram that never renders, an SSR crash, a peer warning — and follow the most likely causes to a fix. If no card matches, the rest of this page routes you by subsystem.

🎨Styles are missing or unstyled

• ✓Reset or index.css imported in the wrong order
• ✓Tailwind / UnoCSS overriding renderer styles
• ✓Peer CSS such as katex.min.css is not imported

Open the CSS checklist

Also read:Tailwind Integration & Style Ordering·Installation

📊Diagrams do not render, or flicker

• ✓Peer package (mermaid, @terrastruct/d2) not installed
• ✓Worker or SSR boundary blocks browser-only rendering
• ✓Fence is still unclosed while the stream is running

Mermaid quick start

Also read:D2 quick start·AntV Infographic

⚙️SSR or build errors (Nuxt, hydration, workers)

• ✓window is not defined during server render or build
• ✓Server and client hydration output mismatch
• ✓Browser-only peer initialized on the server

Nuxt SSR guide

Also read:Troubleshooting

⚡Content jumps or flickers while streaming

• ✓Markdown re-parsed inside MarkdownRender on every token
• ✓nodes + final not used for incremental updates
• ✓Heavy renderers kept on during streaming

AI chat & streaming

Also read:Streaming performance tuning

📦Peer dependency warnings (katex, mermaid)

• ✓Optional peer like katex or mermaid is not installed
• ✓Peer installed but its CSS is missing
• ✓Installed version outside the supported range

Installation guide

Also read:Math rendering with KaTeX

🐢Long documents render slowly

• ✓Whole document re-parsed on every update
• ✓Math, diagrams, or diffs enabled on long inputs
• ✓No chunked or virtualized rendering

Performance guide

Also read:Parser Performance Baseline

Still stuck? Bring diagnostics with you

Copy an issue template with environment, symptom, and reproduction placeholders, then fill it in when you open a GitHub issue.

Already know the subsystem? Jump directly

What you see	Start here	Then go to
Styles look broken, spacing is off, or Tailwind wins	CSS looks wrong? Start here	Tailwind Integration & Style Ordering
A trusted tag like <thinking> renders as raw HTML	Docs Site & VitePress or Custom Tags & Advanced Components	API Reference
window is not defined or browser-only peers crash during SSR	Troubleshooting	Nuxt SSR
Mermaid, KaTeX, stream-diffs, or D2 does not render	Installation	Renderer & Node Components
Chat output feels slow or reparses too much	AI Chat & Streaming	Performance
A built-in node is the wrong shape for your app	Override Built-in Components	Renderer & Node Components

1. Styles look wrong

Symptoms:

• paragraphs, tables, or lists have odd spacing
• code blocks or images look unstyled
• utility classes from Tailwind or UnoCSS override the renderer

Check in this order:

1. import your reset before markstream-vue/index.css
2. if you use Tailwind or UnoCSS, use @import '...' layer(components)
3. if math is enabled, import katex/dist/katex.min.css
4. if the renderer lives in a larger app surface, scope overrides with custom-id

Start with the CSS checklist: Troubleshooting

2. Custom tags or custom components do not appear

Symptoms:

• <thinking> shows up as raw HTML
• your custom Vue component never renders
• the component works in one place but not another

Check in this order:

1. make sure the tag is listed in custom-html-tags
2. register the mapping with setCustomComponents(customId, mapping)
3. render the page with the matching custom-id
4. if you are in VitePress, put the registration in enhanceApp

Best paths:

• docs-site or theme case: Docs Site & VitePress
• app-level custom tags: Custom Tags & Advanced Components

3. SSR errors or browser-only crashes

Symptoms:

• window is not defined
• Mermaid or stream-diffs works locally but fails in SSR
• hydration differs between server and client

Check in this order:

1. confirm whether the failing peer is browser-only
2. move that initialization behind client-only boundaries
3. keep server-safe rendering on the base MarkdownRender path

Best paths:

• general checklist: Troubleshooting
• Nuxt-specific rules: Nuxt SSR

4. Heavy features do not render

Symptoms:

• Mermaid fences stay as source text
• formulas stay blank
• stream-diffs enhanced code blocks fall back to <pre>
• D2 falls back to source

Most of the time, this is not a parser bug. It is one of:

• the peer package is not installed
• required CSS is missing, especially for KaTeX
• SSR or worker boundaries are wrong

Start with Installation, then confirm the component-specific notes in Renderer & Node Components.

5. Streaming or chat output feels slow

Symptoms:

• every token update causes visible reflow
• long chat transcripts get heavy quickly
• the app reparses too much Markdown on each update

The usual fix is architectural rather than cosmetic:

• parse outside MarkdownRender
• pass nodes + final
• keep heavy peers off until they are needed

Best path: AI Chat & Streaming, then Performance

6. Still not sure?

If you still cannot classify the issue:

1. reproduce it in the playground with the smallest Markdown sample possible
2. remove optional peers until the failure becomes simpler
3. compare against the nearest scenario guide: Docs Site & VitePress, AI Chat & Streaming, or Usage & Streaming

If it still looks like a real bug, collect:

• the minimal Markdown sample
• framework/runtime details
• whether Tailwind, UnoCSS, or SSR is involved
• which optional peers are installed

The Copy issue template button at the top of this page bundles these placeholders for you. Then use the hosted test page or issue link from Troubleshooting.