Troubleshooting by Symptom

Use this page when something is wrong but you are not yet sure whether the cause is CSS order, missing peers, SSR boundaries, custom-tag wiring, or renderer choice.

If you already know the exact subsystem, jump straight to the deeper page linked from each section below.

Start with the symptom you see

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, Monaco, 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, wrap the import in @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 Monaco 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
• Monaco blocks are empty
• 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

Then use the hosted test page or issue link from Troubleshooting.