vue-stream-markdown

A markdown renderer specially optimized for streaming scenarios, inspired by streamdown. Designed to achieve smoother streaming rendering through syntax inference and highly customizable rendering elements.

pnpm add vue-stream-markdown

Features

• Streaming-optimized rendering - Incomplete node completion with loading states for images, tables, and code blocks to prevent visual jitter
• Incremental rendering - Leverages Shiki's codeToTokens API for token-level updates, reducing DOM recreation overhead
• Progressive Mermaid rendering - Throttled, streaming-friendly diagram rendering with loading states
• Streaming LaTeX rendering - Progressive math equation rendering with KaTeX support
• Interactive controls - Copy and download buttons for images, tables, and code blocks
• Fully customizable - Replace any AST node with your own Vue components
• Theme-aware scoped styles - Scoped styles under .stream-markdown with semantic data-stream-markdown attributes, following shadcn/ui design system
• Beautiful built-in typography - No atomic CSS required (Tailwind/UnoCSS), self-contained styles
• Content hardening & security - Built-in protection against malicious Markdown with URL validation and protocol blocking
• SSR support - Full server-side rendering compatibility with environment detection utilities

Usage

[!IMPORTANT] 🚧 vue-stream-markdown is currently in active feature development.

Breaking changes are avoided as much as possible, but the project maintains a relatively high release frequency.

If a version meets your needs, you don't need to always follow the latest version.

For detailed usage and API documentation, please refer to the Documentation.

<script setup lang="ts">
import { ref } from 'vue'
import { Markdown } from 'vue-stream-markdown'
import 'vue-stream-markdown/index.css'
// If you don't have shadcn CSS variables globally, import the theme
import 'vue-stream-markdown/theme.css'

const content = ref('# Hello World\n\nThis is a markdown content.')
</script>

<template>
  <Markdown :content="content" />
</template>

Credit

This project is inspired by streamdown and even uses some source code from it.

This project also uses and benefits from:

• mdast - Markdown Abstract Syntax Tree format
• Shiki - Beautiful syntax highlighting
• Mermaid - Diagramming and charting tool
• KaTeX - Fast math typesetting library for the web
• Remend - This project implements similar functionality inspired by remend for intelligently parsing and completing incomplete Markdown blocks.

Code Sources

• markstream-vue - The original inspiration for learning AST-based custom markdown rendering, and the source of the animation implementation used in this project
• ast-explorer - Learned AST knowledge from this project, and the playground layout inspiration and AST syntax tree filtering code are derived from it
• medium-zoom - Inspired the custom image zoom implementation
• markdown-sanitizers - URL validation and security hardening logic in src/utils/harden.ts is ported from rehype-harden
• Dify - LaTeX preprocessing logic in src/preprocess/vendored/markdown-utils.ts is ported from Dify

Acknowledgments

I would like to express my sincere gratitude to those who provided guidance and support during the project selection phase and promotion phase of this project. Without their encouragement and support, I would not have been able to complete this work. In particular, the streamdown community provided excellent code guidance and even helped fix several issues.

Troubleshooting

The playground supports generating shareable links and provides streaming controls (forward/backward navigation) for debugging streaming rendering issues.

If you encounter any problems, please:

1. Use the Generate Share Links button in the playground to create a shareable link with your current content
2. Enable the AST Result toggle to view the parsed AST syntax tree
3. Copy the markdown content and AST syntax tree at the time of the issue

Please provide the shareable link, markdown content, and AST syntax tree when creating an issue. This will help me reproduce and diagnose the problem more effectively.

Contributors

License

MIT License © jinghaihan