介绍

markdown-vue3 是一个轻量、高效的 Markdown 渲染组件，基于 Vue 3 和 markdown-it 开发。
支持常见 Markdown 语法、代码高亮、Vue 插槽、自定义规则，适用于 AI 流式回答、内容管理系统等场景。

依赖版本

• markdown-it: ^14.1.1
• markdown-it-container: ^4.0.0
• vue: ^3.5.30

安装

npm install @npm-brx/markdown-vue3 markdown-it-container
# 或
pnpm add @npm-brx/markdown-vue3 markdown-it-container

可选：代码高亮

npm install highlight.js

快速开始

<template>
  <div class="markdown-body">
    <MarkdownVue3 :md="md" :source="source" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import MarkdownIt from 'markdown-it';
import { MarkdownVue3 } from '@npm-brx/markdown-vue3';

const md = new MarkdownIt({ html: true });
const source = ref('# 标题\n\n这是一段 **Markdown** 内容。');
</script>

思考 / 进度面板

注册 thinking、progress 容器后，可在文档中使用 :::thinking / :::progress，并通过固定区插槽渲染为顶部面板：

| 插槽 | 参数 | 说明 | |------|------|------| | #fixed-thinking | { contents } | 各 thinking 块的内容字符串数组 | | #fixed-progress | { nodes } | 文档中全部 progress 块 |

• 多个 thinking 块会合并显示在同一思考面板
• 多个 progress 块时，进度面板显示最后一个
• 需设置 :containers="['thinking', 'progress']"

<MarkdownVue3
  :md="md"
  :source="source"
  :containers="['thinking', 'progress']"
  :sanitize="sanitize"
>
  <template #fixed-thinking="{ contents }">
    <DefaultThinking :contents="contents" />
  </template>

  <template #fixed-progress="{ nodes }">
    <DefaultProgress :nodes="nodes" />
  </template>
</MarkdownVue3>

Markdown 写法

进度（JSON 任务列表）：

:::progress
```json
[
  { "status": "completed", "content": "理解问题" },
  { "status": "in_progress", "content": "检索数据" },
  { "status": "pending", "content": "输出结论" }
]
```
:::

思考（普通 markdown，可多个块）：

:::thinking
第一段思考，支持 **加粗**、`行内代码` 等。
:::

:::thinking
第二段思考会合并到同一面板。
:::

正文：普通 markdown，可与上述容器穿插书写。

插槽

固定区

• #fixed-thinking="{ contents }"
• #fixed-progress="{ nodes }"

正文区（按需注册）

• #container:<name>="{ node }" — 自定义容器，如 container:tip
• #fence:<lang>="{ node }" — 自定义代码块，配合 :fences="['javascript']"
• #tag:<tag>="{ node }" — 自定义 HTML 标签，配合 :tags="['img']"

DefaultThinking

| Prop | 类型 | 说明 | |------|------|------| | contents | string[] | thinking 块内容列表（必填） | | showHeader | boolean | 是否显示标题栏，默认 true |

支持 #title 插槽自定义标题栏；折叠可调用 ref 上的 setCollapsed / collapsed。

DefaultThinking 需在 MarkdownVue3 子树内使用，内部通过 inject('md') 获取实例以渲染 markdown，无需再手动传入 md。

DefaultProgress

| Prop | 类型 | 说明 | |------|------|------| | nodes | array | progress 块列表（必填） | | icons | object | 可选，任务状态图标 | | showHeader | boolean | 是否显示标题栏，默认 true |

依赖注入

MarkdownVue3 会将传入的 :md 实例通过 provide('md', md) 注册；若设置了 :sanitize，也会 provide('sanitizeHtml', sanitize)。

在 #fixed-thinking、#container:* 等插槽内的自定义子组件中，可直接 inject 获取，无需 prop 透传：

<script setup lang="ts">
import { inject } from 'vue';
import type MarkdownIt from 'markdown-it';

const md = inject('md') as MarkdownIt;
const sanitizeHtml = inject<(html: string) => string>('sanitizeHtml', (html) => html);
</script>

自定义组件需作为 MarkdownVue3 的后代节点渲染（例如放在插槽模板里），否则 inject 取不到值。

流式输出建议

1. 每个 :::thinking / :::progress 块需完整闭合（含结尾 :::）后才会进入面板。
2. 流式追加时，块与块之间保留换行，例如：blocks.slice(0, i).join('\n')。
3. 建议 progress 放在正文区域；thinking 可多次追加，会自动合并。

安全说明

组件内部使用 v-html 渲染 HTML 内容。若 source 来自不可信输入（如用户生成内容），请传入 :sanitize 函数进行 HTML 清洗（例如使用 DOMPurify）。

示例

GitHub：https://github.com/a32211669/markdown-vue3-examples.git