Troubleshooting

If you do not yet know whether the issue is CSS, peers, SSR, or custom-tag wiring, start with Troubleshooting by Symptom first.

If something breaks, here are common fixes:

• Standard Markdown rendering is SSR-safe. If a browser-only peer or worker causes window is not defined, initialize that feature after mount or place only that feature boundary inside Nuxt <ClientOnly>; do not wrap the basic renderer by default.
• Install katex when math rendering fails, and import katex/dist/katex.min.css in your app entry.
• For Mermaid issues, upgrade or pin mermaid to a version >= 11 and check asynchronous render logs.
• If you load KaTeX/Mermaid via CDN <script>, make sure window.katex / window.mermaid exist before first render, or call setKatexLoader(() => window.katex) / setMermaidLoader(() => window.mermaid) once after they load.
• For performance concerns, check that viewportPriority is true and avoid too many heavy nodes in a single mount.

If unsure, reproduce issue using the playground (or the hosted quick test) and then open an issue with stack trace and minimal markdown sample.

Hosted quick test: https://markstream-vue.simonhe.me/test

Open a new issue (quick link): https://github.com/Simon-He95/markstream-vue/issues/new?template=bug_report.yml

Common problems (FAQ)

• Tailwind / CSS utilities overriding styling: If your project uses Tailwind or a component library (e.g., shadcn), utility classes or global styles may override the library's styles. See the Tailwind integration guide for recommended import ordering and strategies: /guide/tailwind.

  Quick fixes:

  • Import markstream-vue/index.css using @import 'markstream-vue/index.css' layer(components); (see the Tailwind page). This controls style ordering.
  • Consider setting a prefix in Tailwind config (e.g., tw-) to avoid collisions with component library class names.
  • Use scoped selectors or :deep to target only the elements you need to override.

  Note: markstream-vue scopes its packaged CSS under an internal .markstream-vue container (including theme variables and Tailwind utilities), so most conflicts come from ordering/resets inside the renderer area rather than global leakage.

• Want to tweak looks? You can customize via CSS variables in src/index.css (e.g., --vscode-editor-background, --vscode-editor-foreground) or override component classes in your app's stylesheet. Use the @apply helper or your own stylesheet to keep style rules isolated.

• Slots first: if the styling you want needs layout changes inside a component, check whether the component provides a named slot (e.g., header-left, header-right, loading). Slots are an easy and stable escape hatch that let you re-render interior markup without overriding internals.

• Still not enough? Use setCustomComponents(id, mapping) to replace an entire renderer for a node with your own Vue component. See the Advanced guide for setCustomComponents usage and how to scope them to a custom-id. Quick example (replace the renderer for code_block nodes scoped to my-docs):

import { setCustomComponents } from 'markstream-vue'

setCustomComponents('my-docs', {
  code_block: MyCustomCodeBlock,
})

This will cause all MarkdownRender instances with custom-id="my-docs" to render the code_block node using MyCustomCodeBlock instead of the default. See Advanced for more examples.

• Repro / report flow: When you run into rendering anomalies or errors, try to reproduce them with the playground app and a minimal markdown sample. If it's still broken, run unit tests locally with pnpm test to rule out regressions. Then open an issue with:

  1. Minimal markdown example that reproduces the problem (include in the issue body or link to a gist).
  2. Steps to reproduce (playground link or playground instructions), and the environment (browser, Node version, Vite/Nuxt).
  3. Any error stack traces and relevant console output.

  Prefer to share a small playground reproduction and include a link; maintainers will triage and ask for more context if needed.

  Extra tip: if you can write a unit/integration test that reproduces the bug, add it under the test/ folder and run pnpm test locally — this is the fastest way for maintainers to validate and fix regressions.

CSS looks wrong? Start here

Most rendering bugs are caused by style ordering, missing resets, or utility frameworks (Tailwind/UnoCSS) trumping component CSS. Run through this checklist before filing an issue:

1. Reset browser defaults — margins on p, dl, table, and pre differ per browser. Import a reset (modern-css-reset, @unocss/reset, or Tailwind's @tailwind base) before markstream-vue styles:

@import 'modern-css-reset';
@tailwind base;
@tailwind components;

@import 'markstream-vue/index.css';

2. Use CSS layers — When Tailwind or UnoCSS runs in @layer components or utilities, use @import '...' layer(components) so the cascade is predictable:

@import 'markstream-vue/index.css' layer(components);

For UnoCSS, inject the CSS inside preflights:

import { defineConfig, presetUno } from 'unocss'

export default defineConfig({
  presets: [presetUno()],
  preflights: [
    {
      layer: 'components',
      getCSS: () => '@import "markstream-vue/index.css";',
    },
  ],
})

3. Double-check peer CSS — KaTeX ships CSS. Missing imports show up as invisible formulas. Mermaid does not require extra CSS.

4. Scope overrides via custom-id — When integrating with larger design systems, renderers can stomp on each other. Add custom-id="docs" to MarkdownRender and apply overrides scoped to [data-custom-id="docs"] so other layouts stay untouched.

If none of the above helps, reproduce the issue in the playground (pnpm play) with a CSS-only snippet and include the link when reporting the bug.

Quick test — run the playground locally to reproduce and debug:

pnpm play
# open the playground and reproduce the issue with a minimal Markdown sample

Next step

Troubleshooting by Symptom→Installation & Optional Peers→Nuxt SSR→