@zjlab-frontier/markdown 使用说明文档

包名：@zjlab-frontier/markdown
适用框架：React（支持 React 18+）
核心引擎：react-markdown + KaTeX / MathJax + mermaid
功能亮点：支持 Mermaid 图表、LaTeX 数学公式（支持 KaTeX 和 MathJax 双引擎）、代码高亮、GitHub 风格 Markdown（GFM）、长代码折叠、一键复制、媒体自动识别 等。

📦 安装

npm install @zjlab-frontier/markdown

⚠️ 前置依赖：本项目依赖 react 和 react-dom (≥18.0.0)。

🚀 快速开始

1. 引入组件

import { ZJMarkdown } from '@zjlab-frontier/markdown';
// 引入样式（如果构建工具没有自动处理）
// import '@zjlab-frontier/markdown/dist/style.css'; 

2. 基本使用

function App() {
  const markdownContent = `
# 欢迎使用 ZJLab Markdown

这是一个功能强大的 React Markdown 组件。

- ✅ **数学公式**：$E = mc^2$
- ✅ **Mermaid 图表**：流程图、时序图等
- ✅ **代码增强**：自动识别语言、复制按钮、长代码折叠
- ✅ **多媒体**：自动识别 mp3/mp4 链接
  `;

  return (
    <div style={{ padding: 20 }}>
      {/* 默认使用 KaTeX 渲染公式 */}
      <ZJMarkdown 
        content={markdownContent} 
        fontSize={16} 
      />
    </div>
  );
}

🧩 功能详解

1. 数学公式（双引擎支持）

组件支持 KaTeX（默认，渲染快）和 MathJax（兼容性强）两种引擎。可以通过 mathEngine 属性切换。

✅ 支持语法：

• 行内公式：$...$ 或 \(...\]
• 块级公式：$$...$$ 或 \[...\]
• 化学式支持：支持 \ce{...} (KaTeX 需扩展，MathJax 原生支持更好)

⚙️ 预处理增强：

组件内置了 LaTeX 预处理逻辑，解决了 Markdown 转义字符（如 \ 和 _）与 LaTeX 语法冲突的问题。

• 自动保护 \\ 换行符
• 自动处理 \ce{...} 和 \boxed{...} 等裸公式

示例：

爱因斯坦质能方程：$E = mc^2$

高斯积分：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} 
$$

切换引擎示例：

<ZJMarkdown 
  content={content} 
  mathEngine="mathjax" // 切换为 MathJax 引擎
/>

2. Mermaid 图表渲染

在代码块中标注语言为 mermaid 即可自动渲染图表。

示例：

```mermaid
graph TD
  A[Start] --> B{Is it?}
  B -->|Yes| C[OK]
  B -->|No| D[Cancel]
```

3. 代码块增强

• 语言标注：显示语言类型（如 typescript）。
• 一键复制：提供复制按钮。
• 自动折叠：高度超过 400px 自动折叠，点击“查看全部”展开。
• 自动换行：对文本类语言（text, md, latex 等）强制换行，避免横向滚动。

4. GitHub 风格 Markdown (GFM)

集成 remark-gfm，支持表格、任务列表、删除线等。

5. 媒体自动识别

• 音频 (.mp3, .wav 等) → <audio controls>
• 视频 (.mp4, .webm 等) → <video controls>

🎨 样式与自定义

组件根元素默认带有 .markdown-body 类。

Props 属性

| 属性名 | 类型 | 默认值 | 说明 | |:---|:---|:---|:---| | content | string | 必填 | Markdown 源码字符串 | | mathEngine | 'katex' , 'mathjax' | 'katex' | 数学公式渲染引擎 | | fontSize | number | 16 | 正文字体大小 (px) | | fontFamily | string | 'inherit' | 字体设置 | | style | CSSProperties | - | 自定义根元素样式 |

🛠️ 开发与构建

npm run build        # 构建产物
npm run build:types  # 生成类型定义

📝 License

MIT