API guide

This page connects the parser helpers, renderer props, and customization hooks exposed by markstream-vue. Pair it with the Usage and Props pages when wiring everything together.

Render pipeline at a glance

Markdown string → getMarkdown() → markdown-it-ts instance
            ↓
   parseMarkdownToStructure(content, md) → AST (BaseNode[])
            ↓
   <MarkdownRender> → node components (CodeBlockNode, ImageNode, …)

You can jump in at any stage:

• Provide content to let the component handle parsing automatically.
• Provide nodes when you need full control over the AST (server-side parsing, custom transforms).

Parser helpers

Helper	Purpose	When to use
getMarkdown(msgId?, options?)	Returns a configured markdown-it-ts instance with the plugins this package expects.	Customize parser options (HTML toggles, additional plugins) before transforming tokens.
parseMarkdownToStructure(content, md)	Generates the AST consumed by MarkdownRender from a Markdown string.	Pre-parse on the server, run validations, or reuse the AST across renders.

Both helpers are framework-agnostic and can run in Node or the browser. For large documents you can reuse the md instance between parses to avoid re-initializing plugins.

Custom components & scoping

Use setCustomComponents(customId?, mapping) to override any node renderer. Pair it with the custom-id prop on MarkdownRender so replacements stay scoped.

import { setCustomComponents } from 'markstream-vue'
import CustomImageNode from './CustomImageNode.vue'

setCustomComponents('docs', {
  image: CustomImageNode,
})

<MarkdownRender custom-id="docs" :content="md" />

Tips:

• Use descriptive IDs (docs, playground, pdf-export) for tracing.
• Call setCustomComponents(mapping) to set globals, but prefer scoped IDs to avoid surprises in multi-instance apps.
• Clean up mappings in SPA routers if you register them dynamically.

Parse hooks & transforms

When passing content, you can intercept parser stages through parse-options (prop) or the ParseOptions parameter of parseMarkdownToStructure.

Hooks:

• preTransformTokens(tokens) — mutate tokens before default handling.
• postTransformTokens(tokens) — inspect/adjust tokens before node generation.

If you need to reshape the AST, post-process the returned nodes and pass them to MarkdownRender via nodes.

Example: render AI “thinking” tags as custom components (no hooks needed):

import { setCustomComponents } from 'markstream-vue'
import ThinkingNode from './ThinkingNode.vue'

setCustomComponents('docs', { thinking: ThinkingNode })

<MarkdownRender
  custom-id="docs"
  :custom-html-tags="['thinking']"
  :content="doc"
/>

Hooks remain useful if you want to reshape the emitted thinking node (strip wrappers, remap attrs, merge blocks, etc.), or post-process the parsed nodes before rendering.

Utility exports

Besides the core renderer and parser helpers, the package exposes:

• CodeBlockNode, MarkdownCodeBlockNode, MermaidBlockNode, MathBlockNode, ImageNode, etc. — see Components for their props and CSS requirements.
• VueRendererMarkdown (global component plugin) and shared type exports (component prop interfaces, parser types).

For parser types and hooks, see /guide/parser-api (or the stream-markdown-parser README on npm).

Styling + troubleshooting reminders

• Always include a reset before markstream-vue/index.css and wrap it with @layer components when using Tailwind or UnoCSS. See the Tailwind guide and the CSS checklist.
• Code/graph peers: KaTeX needs its own CSS import; Mermaid does not. Missing KaTeX styles often manifest as invisible formulas.
• Use custom-id to scope overrides and avoid global selector conflicts.

Need more examples? Jump into the Playground or run pnpm play locally to experiment with custom parsers and renderers.