Usage

This guide covers installation instructions, basic usage examples, and provides an overview of all available configuration options. For detailed configuration documentation, see the quick links section below.

Installation

pnpm add vue-stream-markdown

Peer Dependencies

Since some users may not need complex rendering features like code blocks, Mermaid diagrams, or mathematical formulas, shiki, mermaid, and katex are provided as peer dependencies. If you need these rendering features, please install them manually:

# For code syntax highlighting
pnpm add shiki

# For Mermaid diagram rendering
pnpm add mermaid

# For LaTeX math rendering
pnpm add katex

Basic Usage

By default, the component runs in streaming mode, which is optimized for progressive content updates. You can also use static mode for complete markdown content:

<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>
  <!-- Streaming mode (default) -->
  <Markdown :content="content" mode="streaming" />

  <!-- Static mode -->
  <Markdown :content="content" mode="static" />
</template>

Configuration

Core Props

• content (string): The markdown content to render
• mode ('streaming' | 'static'): Rendering mode, defaults to 'streaming'
• enableAnimate (boolean | undefined): Enable typewriter animation effect. When undefined, automatically enabled in 'streaming' mode and disabled in 'static' mode
• isDark (boolean): Enable dark mode
• locale (string | LocaleConfig): Locale for internationalization, defaults to 'en-US'

Code Highlighting

• shikiOptions (ShikiOptions): Configuration for Shiki code highlighting

Mermaid Diagrams

• mermaidOptions (MermaidOptions): Configuration for Mermaid diagram rendering

LaTeX Math

• katexOptions (KatexOptions): Configuration for KaTeX math rendering

Controls

• controls (boolean | ControlsConfig): Enable or configure interactive controls (copy, download, etc.)

Previewers

• previewers (boolean | PreviewerConfig): Enable or configure previewers for any programming language. By default, HTML and Mermaid have built-in previewers. You can add custom previewers for any language.

Quick Links

For detailed configuration options, see the corresponding sections in the Config documentation:

• Parser Options - Customize markdown parsing behavior (affects how markdown is parsed and transformed)
• Display Options - Configure display settings (affects Shiki, Mermaid, KaTeX, images, and code blocks)
• Controls - Detailed control configuration (affects interactive buttons like copy, download, etc.)
• Previewers - Configure previewer components for any programming language (affects code block preview rendering)
• Security - Security and hardening options (affects URL validation and protocol blocking)
• Custom Renderers - Replace default renderers with custom components (affects how each AST node type is rendered)
• Internationalization - Locale and translation configuration (affects all text content in the component)