vue-stream-markdown

The core library handles basic markdown, but advanced features are provided via separate extension packages. To support specific content types, you must include the corresponding package:

• Code Highlighting: For syntax highlighting in code blocks.
• Math: For rendering mathematical notation.
• Mermaid: For rendering diagrams.
• Beautiful Mermaid: For enhanced Mermaid diagram rendering.

Note: Some integrations (like ECharts) may be custom implementations within specific environments like the Playground and are not part of the core library extensions.

The rendering pipeline follows a single rule: callers must always provide the complete Markdown source currently available. The pipeline operates in two modes:

1. Streaming Mode (mode="streaming"): The pipeline uses Markmend completion to repair unfinished syntax (like partial links, tables, or code fences) in the changing tail of the document. This ensures partial structures remain readable as text arrives.
2. Static Mode (mode="static"): Completion is skipped, and the source is parsed as-is.

The Workflow: Complete source $\rightarrow$ Rendering mode $\rightarrow$ Markmend completion (if streaming) $\rightarrow$ Incremental Comark parsing $\rightarrow$ Stable Vue nodes $\rightarrow$ Rich renderers (if configured).

The library supports two modes of operation:

1. Streaming Mode: During active streaming, the underlying parser (Markmend) completes supported unfinished syntax (e.g., closing an open code block or list item) to ensure the UI renders correctly as chunks arrive.
2. Static Mode: Parses the original source without attempting to complete unfinished syntax. This is typically used when the stream has finished or for pre-rendered content.

Use streaming mode when you want to provide a real-time, growing response experience (like an LLM output).

To ensure performance and visual stability during streaming:

• Incremental Parsing: The Markdown instance uses a long-lived Comark parser. Instead of re-parsing the entire document from scratch, it reuses the stable source prefix and only parses the changed tail. If a parse fails, the last successfully rendered document remains visible.
• Stable Vue Output: The Comark document is rendered directly to Vue nodes. Top-level blocks maintain stable identities, meaning growing content at the end of a stream does not cause earlier paragraphs, controls, or interactive components to be replaced or re-rendered unnecessarily.
• Synchronous vs. Asynchronous Rendering: Simple semantic elements render synchronously. Complex features (math, diagrams, code highlighting) use dedicated Vue components only when required by the document content.

When defaultOrigin is set, any relative URLs found in the Markdown content will be automatically resolved against that origin. For example, a link to /docs/guide will become https://your-app.com/docs/guide if the defaultOrigin is https://your-app.com.

{
  defaultOrigin: 'https://your-app.com'
}

The library includes a built-in Comark security plugin that validates links and image URLs using hardenOptions.

Key Security Behaviors:

• Event Handlers: Vue event-handler sources (e.g., onclick) are not executed as template expressions. Instead, parsed attributes are passed as ordinary VNode attributes.
• Custom Components: You are responsible for the security of custom components. Only register components you trust. If a custom component interprets attributes as executable code or injects raw HTML, that component is responsible for its own security boundary.

You can use both @stream-markdown/beautiful-mermaid and @stream-markdown/mermaid simultaneously to get the best of both worlds. The selection order is deterministic:

1. Beautiful Mermaid renders diagram types it supports.
2. Standard Mermaid renders any unsupported Beautiful Mermaid diagram types.
3. If no configured extension supports the diagram, the source code block remains visible as a standard code block.

This setup allows you to have polished styling for common diagrams while maintaining full syntax coverage for complex ones.

import { beautifulMermaid } from '@stream-markdown/beautiful-mermaid'
import { mermaid } from '@stream-markdown/mermaid'

const extensions = {
  beautifulMermaid: beautifulMermaid(),
  mermaid: mermaid(),
}