yy-markdown

功能强大的 Markdown 处理工具包，支持代码高亮、Mermaid 流程图、引用链接、图片处理、流式渲染等功能。

✨ 特性

• 📝 完整的 Markdown 支持 - 基于 markdown-it，支持完整的 Markdown 语法
• 🎨 代码高亮 - 集成 highlight.js，支持多种编程语言，带复制按钮和行号
• 🖼️ 图片处理 - 自动优化、点击预览、链接图片支持
• 📊 Mermaid 图表 - 流程图、时序图、甘特图等
• 🔗 引用链接 - 支持文档引用、Tooltip 展示
• ⚡ 流式渲染 - 支持 SSE 实时渲染，块解析和内容去重
• 📋 代码复制 - 一键复制代码块
• 🎯 性能优化 - 内容去重、智能缓存

📦 安装

npm install yy-markdown

🚀 快速开始

基础使用

import { createMarkdown, processMarkdown } from 'yy-markdown';

// 创建 Markdown 实例
const md = createMarkdown();

// 处理 Markdown 内容
const html = processMarkdown(md, '# Hello World\n\n这是一段 **Markdown** 文本。');

完整功能使用

import { 
  createMarkdown, 
  processMarkdown, 
  parseMarkdownBlocks 
} from 'yy-markdown';

// 创建 Markdown 实例（启用代码高亮）
const md = createMarkdown({}, { enableCodeHighlight: true });

// 处理 Markdown（包含引用链接和图片处理）
const html = processMarkdown(md, markdownContent, {
  references: [
    {
      index: '1',
      name: '文档标题',
      url: 'https://example.com',
      summary: '文档摘要...',
      type: 'doc'
    }
  ],
  onPreview: (src) => {
    console.log('预览图片:', src);
  }
});

// 流式渲染 - 解析为块
const blocks = parseMarkdownBlocks(chunks, {
  id: 'message-1',
  history: false
});

📚 API 文档

createMarkdown(config, options)

创建并配置 MarkdownIt 实例。

参数：

• config (Object, 可选) - MarkdownIt 配置选项
• options (Object, 可选) - 选项
  • enableCodeHighlight (boolean, 默认: true) - 是否启用完整代码高亮（带复制按钮和行号）

返回： MarkdownIt 实例

示例：

const md = createMarkdown({
  html: true,
  linkify: true
}, {
  enableCodeHighlight: true
});

processMarkdown(md, content, options)

处理 Markdown 内容，包括引用链接和图片处理。

参数：

• md (MarkdownIt) - MarkdownIt 实例
• content (string) - Markdown 内容
• options (Object, 可选) - 处理选项
  • references (Array, 可选) - 引用列表
  • onPreview (Function, 可选) - 图片预览回调

返回： 处理后的 HTML 字符串

示例：

const html = processMarkdown(md, content, {
  references: [
    { index: '1', name: '文档', url: 'https://example.com' }
  ],
  onPreview: (src) => {
    // 处理图片预览
  }
});

parseMarkdownBlocks(content, options)

解析 Markdown 内容为块数组，支持流式渲染。

参数：

• content (Array|string) - 内容（可以是数组块或字符串）
• options (Object, 可选) - 配置选项
  • id (string, 默认: 'markdown') - 唯一标识符
  • history (boolean, 默认: false) - 是否为历史记录（不解析）

返回： 解析后的块数组

示例：

// 流式内容
const chunks = [
  { id: '1', data: '```javascript\n' },
  { id: '2', data: 'const x = 1;\n' },
  { id: '3', data: '```' }
];

const blocks = parseMarkdownBlocks(chunks, {
  id: 'message-1'
});

// blocks: [
//   { id: 'message-1-1-code', type: 'code', lang: 'javascript', content: 'const x = 1;\n' }
// ]

createCodeHighlight(md)

创建代码高亮函数（带复制按钮和行号）。

参数：

• md (MarkdownIt) - MarkdownIt 实例

返回： 高亮函数

processReferences(html, references)

处理引用链接。

参数：

• html (string) - HTML 内容
• references (Array) - 引用列表

返回： 处理后的 HTML

processImages(html, options)

处理图片。

参数：

• html (string) - HTML 内容
• options (Object, 可选) - 选项
  • onPreview (Function, 可选) - 预览回调

返回： 处理后的 HTML

createBlockParser(options)

创建块解析器。

参数：

• options (Object, 可选) - 配置选项
  • id (string, 默认: 'markdown') - 唯一标识符

返回： 解析器对象

🎨 工具函数

normalizeLineBreaks(content)

处理内容换行。

safeStringify(content)

安全地将内容转换为字符串。

escapeRegExp(str)

转义正则表达式特殊字符。

isMobile()

检查是否为移动设备。

generateUniqueId()

生成唯一 ID。

getContentFingerprint(content, type)

生成内容指纹用于去重。

generateLineNumbers(linesLength)

生成行号 HTML。

📋 常量

CODE_STYLES

代码样式常量。

IMAGE_STYLES

图片样式常量。

CONTENT_LIMITS

内容长度限制。

MARKDOWN_CONFIG

MarkdownIt 默认配置。

🔧 高级用法

自定义代码高亮

import { createMarkdown, createCodeHighlight } from 'yy-markdown';

const md = createMarkdown();
md.options.highlight = createCodeHighlight(md);

流式渲染示例

import { parseMarkdownBlocks } from 'yy-markdown';

// SSE 流式数据
const chunks = [
  { id: '1', data: '# 标题\n\n' },
  { id: '2', data: '这是一段内容。\n\n' },
  { id: '3', data: '```javascript\n' },
  { id: '4', data: 'console.log("hello");\n' },
  { id: '5', data: '```' }
];

const blocks = parseMarkdownBlocks(chunks, { id: 'stream-1' });

// 渲染每个块
blocks.forEach(block => {
  if (block.type === 'markdown') {
    // 渲染 markdown
  } else if (block.type === 'code') {
    // 渲染代码块
  } else if (block.type === 'img') {
    // 渲染图片
  }
});

引用链接处理

import { processReferences } from 'yy-markdown';

const html = '<a href="#ref:doc1">1</a>';
const references = [
  {
    index: 'doc1',
    name: '文档标题',
    url: 'https://example.com/doc',
    summary: '这是文档摘要...',
    type: 'doc'
  }
];

const processed = processReferences(html, references);

📝 注意事项

1. 代码复制功能：需要在全局对象 window.__mdRenderer__.copyCode 上注册复制函数，或使用默认的 Clipboard API。

2. 图片预览功能：需要在全局对象 window.__mdRenderer__.preview 上注册预览函数。

3. 引用链接点击：需要在全局对象 window.__mdRenderer__.openUrl 上注册打开链接函数。

4. 样式依赖：代码高亮需要引入 highlight.js 的 CSS 样式文件。

📄 License

MIT