x-markdown-vue

Vue3 Markdown 渲染器 —— GFM · Shiki 代码高亮 · Mermaid 图表 · LaTeX 数学公式 · 流式动画。

在线演示

安装

pnpm add @flowporr/x-markdown-vue
# 可选能力：代码高亮 / 图表（未安装时优雅降级）
pnpm add shiki shiki-stream mermaid

基本用法

<script setup lang="ts">
import { ref } from 'vue'
import { MarkdownRenderer } from '@flowporr/x-markdown-vue'
import '@flowporr/x-markdown-vue/style'

const md = ref(`# Hello **World**

\`\`\`js
console.log('Hello')
\`\`\`

$$E = mc^2$$`)
</script>

<template>
  <MarkdownRenderer :markdown="md" :is-dark="isDark" enable-animate />
</template>

导出

// 高层组件（主要使用）
export { MarkdownRenderer, MarkdownRendererAsync } from '@flowporr/x-markdown-vue'
// 核心引擎（高级定制）
export { VueMarkdown, VueMarkdownAsync } from '@flowporr/x-markdown-vue'
// 处理器工厂（自定义 pipeline）
export { createProcessor, useMarkdownProcessor } from '@flowporr/x-markdown-vue'
// HAST 渲染（自定义渲染逻辑）
export { render, renderChildren, getVNodeInfos } from '@flowporr/x-markdown-vue'
// 样式
import '@flowporr/x-markdown-vue/style'

MarkdownRenderer Props

渲染开关

Prop	类型	默认值	说明
markdown	string	''	Markdown 原始字符串
allowHtml	boolean	false	是否允许原始 HTML（需配合 sanitize）
enableLatex	boolean	true	启用 LaTeX 数学公式（KaTeX 渲染）
enableAnimate	boolean	false	启用流式逐字动画（Intl.Segmenter 分词）
enableBreaks	boolean	true	换行符转 <br>（remark-breaks）
enableGfm	boolean	true	GFM（表格/任务列表/删除线）
enableShiki	boolean	true	Shiki 代码高亮（需安装 shiki）
enableMermaid	boolean	true	Mermaid 图表（需安装 mermaid）

外观

Prop	类型	默认值	说明
isDark	boolean	false	暗色模式（Shiki 主题 + CSS 类）
shikiTheme	[BuiltinTheme, BuiltinTheme]	['vitesse-light', 'vitesse-dark']	[浅色, 深色] 主题
showCodeBlockHeader	boolean	true	代码块工具栏（语言标签 + 复制）
stickyCodeBlockHeader	boolean	false	代码块头部 sticky
enableCodeLineNumber	boolean	true	代码块行号
codeLineNumberStart	number	1	行号起始值
codeMaxHeight	string	undefined	代码块最大高度（如 '400px'）

安全与扩展

Prop	类型	默认值	说明
sanitize	boolean	false	HTML 安全过滤（DOMPurify + rehype-sanitize）
sanitizeOptions	SanitizeOptions	{}	安全过滤选项
customAttrs	CustomAttrs	{}	自定义 HTML 属性
codeXRender	Record<string, any>	{}	自定义代码渲染器
codeBlockActions	CodeBlockAction[]	undefined	代码块额外操作按钮
mermaidActions	MermaidAction[]	undefined	Mermaid 额外操作按钮
mermaidConfig	Record<string, any>	undefined	Mermaid 初始化配置
remarkPlugins	PluggableList	[]	额外 remark 插件（默认插件之后）
remarkPluginsAhead	PluggableList	[]	额外 remark 插件（默认插件之前）
rehypePlugins	PluggableList	[]	额外 rehype 插件（默认插件之后）
rehypePluginsAhead	PluggableList	[]	额外 rehype 插件（默认插件之前）
rehypeOptions	Record<string, any>	{}	传递给 remark-rehype 的选项

Slots — 覆盖任意元素渲染

支持命名插槽覆盖任意 HTML 元素，插槽名即 HTML 标签名：

插槽名	对应元素	Scope 额外属性
h1 ~ h6	标题	level: number
heading	所有标题（优先级低于具体级别）	level: number
code	所有代码	language, content, inline
inline-code	内联代码	language, content, inline: true
block-code	代码块	language, content, inline: false
ul / ol	列表	ordered, depth
list	所有列表	ordered, depth
li	列表项	ordered, depth, index
list-item	所有列表项	ordered, depth, index
td / th / tr	表格元素	isHead: boolean

<MarkdownRenderer :markdown="md">
  <template #h1="{ level, children }">
    <h1 :class="`heading-${level}`"><component :is="children" /></h1>
  </template>
</MarkdownRenderer>

可选能力依赖

包	用途	缺失时行为
shiki ^3.0	代码高亮（可选）	降级为纯文本代码块
shiki-stream ^0.1	流式 token 化（可选）	Shiki 不可用
mermaid ^11.0	图表渲染（可选）	Mermaid 代码块显示为普通代码

Shiki 体积大（~20MB 含语法/主题）、Mermaid ~3MB，因此动态 import() + peerDependenciesMeta.optional，消费方按需安装。

子菜单

• 代码高亮 — Shiki 多语言高亮
• Mermaid 图表 + LaTeX 公式 — 图表与数学公式
• 流式动画 — 逐词入场动画
• 自定义扩展 — customAttrs / codeXRender / 插件 / 主题