React Markdown Mermaid

English README

一个用于在React应用中渲染Mermaid图表的轻量级组件和rehype插件。支持在react-markdown中自动渲染Mermaid图表，也可以独立使用

如果你需要更为完善的 mermaid 渲染组件，推荐您使用 ds-markdown-mermaid-plugin

📦 安装

npm install react-markdown-mermaid
# 或
yarn add react-markdown-mermaid
# 或
pnpm add react-markdown-mermaid

🚀 快速开始

1. 与 react-markdown 集成

import React from 'react';
import ReactMarkdown from 'react-markdown';
import { rehypeMermaid, MermaidBlock } from 'react-markdown-mermaid';

const App = () => {
  const markdown = `
# 我的文档

这是一个流程图：

\`\`\`mermaid
graph TD
  A[开始] --> B{判断条件}
  B -->|是| C[处理A]
  B -->|否| D[处理B]
  C --> E[结束]
  D --> E
\`\`\`

这是一个序列图：

\`\`\`mermaid
sequenceDiagram
  participant 用户
  participant 系统
  participant 数据库
  
  用户->>系统: 登录请求
  系统->>数据库: 验证用户
  数据库-->>系统: 返回结果
  系统-->>用户: 登录响应
\`\`\`
  `;

  return (
    <ReactMarkdown
      rehypePlugins={[
        [
          rehypeMermaid,
          {
            mermaidConfig: {
              theme: 'default',
              flowchart: { useMaxWidth: true },
            },
          },
        ],
      ]}
      components={{
        MermaidBlock: MermaidBlock,
      }}
    >
      {markdown}
    </ReactMarkdown>
  );
};

2. 基本用法 - 独立组件

import React from 'react';
import { Mermaid } from 'react-markdown-mermaid';

const App = () => {
  const chart = `
    graph TD
      A[开始] --> B{判断条件}
      B -->|是| C[处理A]
      B -->|否| D[处理B]
      C --> E[结束]
      D --> E
  `;

  return (
    <div>
      <h1>流程图示例</h1>
      <Mermaid code={chart} />
    </div>
  );
};

📚 API 文档

Mermaid 组件

独立的Mermaid图表组件。

Props

| 属性 | 类型 | 默认值 | 描述 | | ------------- | ------------------------ | ---------------------------- | ---------------- | | chart | string | - | Mermaid图表代码 | | config | MermaidConfig | - | Mermaid配置选项 | | id | string | 自动生成 | 图表ID | | className | string | 'react-markdown-mermaid' | CSS类名 | | style | CSSProperties | - | 内联样式 | | onLoad | () => void | - | 加载完成回调 | | onError | (error: Error) => void | - | 错误回调 | | onRender | () => void | - | 渲染完成回调 | | showLoading | boolean | true | 是否显示加载状态 | | loadingText | string | 'Loading diagram...' | 加载文本 | | errorText | string | 'Failed to render diagram' | 错误文本 |

示例

import { Mermaid } from 'react-markdown-mermaid';

<Mermaid
  code={chartCode}
  config={{
    theme: 'dark',
    flowchart: { useMaxWidth: true },
  }}
  className="my-mermaid"
  onLoad={() => console.log('图表加载完成')}
  onError={(error) => console.error('渲染错误:', error)}
/>;

MermaidBlock 组件

专门为rehype插件设计的组件。

Props

| 属性 | 类型 | 默认值 | 描述 | | --------------- | ------------------------ | ---------------------------- | ---------------- | | code | string | - | Mermaid图表代码 | | mermaidConfig | MermaidConfig | - | Mermaid配置 | | id | string | 自动生成 | 图表ID | | className | string | 'mermaid-block' | CSS类名 | | style | CSSProperties | - | 内联样式 | | onLoad | () => void | - | 加载完成回调 | | onError | (error: Error) => void | - | 错误回调 | | onRender | () => void | - | 渲染完成回调 | | showLoading | boolean | true | 是否显示加载状态 | | loadingText | string | 'Loading diagram...' | 加载文本 | | errorText | string | 'Failed to render diagram' | 错误文本 |

示例

import { MermaidBlock } from 'react-markdown-mermaid';

<MermaidBlock
  code={chartCode}
  mermaidConfig={{
    theme: 'dark',
    flowchart: { useMaxWidth: true },
  }}
  className="my-mermaid-block"
  onLoad={() => console.log('图表加载完成')}
  onError={(error) => console.error('渲染错误:', error)}
  onRender={() => console.log('图表渲染完成')}
  showLoading={true}
  loadingText="正在渲染图表..."
  errorText="图表渲染失败"
/>;

rehypeMermaid 插件

用于在react-markdown中自动处理Mermaid代码块。

选项

| 属性 | 类型 | 默认值 | 描述 | | --------------- | ----- | ------ | ----------- | | mermaidConfig | any | - | Mermaid配置 |

🎨 样式定制

导入样式

import 'react-markdown-mermaid/style.css';

自定义样式

/* 自定义Mermaid组件样式 */
.react-markdown-mermaid {
  border: 1px solid #e1e5e9;
  border-radius: 8px;
  padding: 16px;
  margin: 16px 0;
}

/* 加载状态样式 */
.react-markdown-mermaid.loading {
  background-color: #f8f9fa;
}

/* 错误状态样式 */
.react-markdown-mermaid.error {
  background-color: #f8d7da;
  color: #721c24;
}

📊 支持的图表类型

1. 流程图 (Flowchart)

graph TD
  A[开始] --> B{判断}
  B -->|是| C[处理]
  B -->|否| D[结束]

2. 序列图 (Sequence Diagram)

sequenceDiagram
  participant 用户
  participant 系统
  用户->>系统: 请求
  系统-->>用户: 响应

3. 甘特图 (Gantt Chart)

gantt
  title 项目计划
  section 设计
  需求分析 :done, des1, 2024-01-01, 2024-01-10
  系统设计 :active, des2, 2024-01-11, 2024-01-25

4. 类图 (Class Diagram)

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

5. 饼图 (Pie Chart)

pie title 浏览器市场份额
  "Chrome" : 65.5
  "Firefox" : 15.2
  "Safari" : 12.3

6. 状态图 (State Diagram)

stateDiagram-v2
  [*] --> 待机
  待机 --> 运行 : 启动
  运行 --> 暂停 : 暂停
  暂停 --> 运行 : 恢复

🔧 高级配置

Mermaid 配置

const mermaidConfig = {
  theme: 'default', // 或 'dark', 'forest', 'neutral'
  flowchart: {
    useMaxWidth: true,
    htmlLabels: true,
  },
  sequence: {
    useMaxWidth: true,
    diagramMarginX: 50,
    diagramMarginY: 10,
  },
  gantt: {
    useMaxWidth: true,
  },
};

错误处理

<Mermaid
  code={chartCode}
  onError={(error) => {
    console.error('Mermaid渲染错误:', error);
    // 显示友好的错误信息
  }}
  errorText="图表渲染失败，请检查语法"
/>

📝 完整示例

1. 基本示例

import React from 'react';
import { Mermaid } from 'react-markdown-mermaid';
import 'react-markdown-mermaid/style.css';

const BasicExample = () => {
  const flowchart = `
    graph TD
      A[开始] --> B{判断条件}
      B -->|是| C[处理A]
      B -->|否| D[处理B]
      C --> E[结束]
      D --> E
  `;

  const sequenceDiagram = `
    sequenceDiagram
      participant 用户
      participant 系统
      participant 数据库
      
      用户->>系统: 登录请求
      系统->>数据库: 验证用户
      数据库-->>系统: 返回结果
      系统-->>用户: 登录响应
  `;

  return (
    <div>
      <h2>流程图</h2>
      <Mermaid code={flowchart} />

      <h2>序列图</h2>
      <Mermaid code={sequenceDiagram} />
    </div>
  );
};

2. Markdown 集成示例

import React from 'react';
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import { rehypeMermaid, MermaidBlock } from 'react-markdown-mermaid';
import 'react-markdown-mermaid/style.css';

const MarkdownExample = () => {
  const markdown = `
# 项目文档

## 系统架构

\`\`\`mermaid
graph TD
  A[前端] --> B[API网关]
  B --> C[用户服务]
  B --> D[订单服务]
  C --> E[数据库]
  D --> E
\`\`\`

## 用户登录流程

\`\`\`mermaid
sequenceDiagram
  participant U as 用户
  participant F as 前端
  participant A as API
  participant D as 数据库
  
  U->>F: 输入用户名密码
  F->>A: 发送登录请求
  A->>D: 查询用户信息
  D-->>A: 返回用户数据
  A-->>F: 返回登录结果
  F-->>U: 显示登录状态
\`\`\`

## 项目进度

\`\`\`mermaid
gantt
  title 项目开发计划
  dateFormat YYYY-MM-DD
  section 设计阶段
  需求分析    :done, des1, 2024-01-01, 2024-01-10
  系统设计    :active, des2, 2024-01-11, 2024-01-25
  section 开发阶段
  编码实现    :dev1, 2024-01-26, 2024-02-15
  测试调试    :dev2, 2024-02-16, 2024-02-28
\`\`\`
  `;

  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm]}
      rehypePlugins={[
        [
          rehypeMermaid,
          {
            mermaidConfig: {
              theme: 'default',
              flowchart: { useMaxWidth: true },
              sequence: { useMaxWidth: true },
              gantt: { useMaxWidth: true },
            },
          },
        ],
      ]}
      components={{
        MermaidBlock: MermaidBlock,
      }}
    >
      {markdown}
    </ReactMarkdown>
  );
};

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置

# 克隆仓库
git clone https://github.com/your-username/react-markdown-mermaid.git
cd react-markdown-mermaid

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建库
npm run build

📄 许可证

MIT License

🔗 相关链接

• Mermaid 官方文档
• React Markdown
• Rehype

如果这个库对你有帮助，请给它一个 ⭐️！