# mermaid-it-markdown

[![npm version](https://img.shields.io/npm/v/mermaid-it-markdown.svg)](https://www.npmjs.com/package/mermaid-it-markdown)
[![npm downloads](https://img.shields.io/npm/dm/mermaid-it-markdown.svg)](https://www.npmjs.com/package/mermaid-it-markdown)
[![License](https://img.shields.io/npm/l/mermaid-it-markdown.svg)](LICENSE)

一个为 [markdown-it](https://github.com/markdown-it/markdown-it) 提供 **Mermaid 图表支持** 的插件。

通过本插件，你可以在 Markdown 中直接使用 ```mermaid 代码块，渲染出流程图、时序图、甘特图等丰富的可视化图表。

📚 **[查看说明文档与在线 Demo](https://fangjc1986.github.io/vue3-blog-vitepress/frontend-components/mermaid-it-markdown.html)** | 🇺🇸 [English Documentation](https://gitee.com/ericfang/markdown-it-mermaid/blob/master/README.md)

## 功能特性

- 🚀 轻松集成到 markdown-it
- 📊 支持所有 Mermaid 图表类型（流程图、时序图、甘特图等）
- ⚡ 高效的渲染和缓存机制
- 🔧 可配置选项
- 🌐 适用于浏览器环境

## 安装

本插件依赖官方的 `mermaid` 库，请一并安装：

```bash
npm install mermaid-it-markdown mermaid --save
# 或
yarn add mermaid-it-markdown mermaid
```

> 💡 注意：确保你的项目中已正确引入并初始化 `mermaid`（例如在页面加载后调用 `mermaid.initialize()`）。

## 使用方式

### 在 markdown-it 中使用

```js
const md = require('markdown-it')();
const mermaidItMarkdown = require('mermaid-it-markdown');

md.use(mermaidItMarkdown);
```

### 在 Vue.js 和 mavon-editor 中使用

```js
import MavonEditor from 'mavon-editor';
import 'mavon-editor/dist/css/index.css';
import mermaidItMarkdown from 'mermaid-it-markdown';

const markdownIt = MavonEditor.getMarkdownIt();
markdownIt.use(mermaidItMarkdown);
```

### 在 VitePress 中使用

```js
// .vitepress/config.js
import mermaidItMarkdown from 'mermaid-it-markdown'

export default {
  markdown: {
    config(md) {
      md.use(mermaidItMarkdown)
    }
  }
}
```

## Markdown 语法示例

在你的 Markdown 文件中，使用如下语法即可嵌入 Mermaid 图表：

````markdown
```mermaid
flowchart TD
    A[Hard] -->|Text| B(Round)
    B --> C{Decision}
    C -->|One| D[Result 1]
    C -->|Two| E[Result 2]
```
````

## API

### 插件选项

插件在初始化时接受配置选项：

```js
md.use(mermaidItMarkdown, {
  // 在此处添加自定义选项（如需要）
});
```

### Mermaid 配置

你可以通过在使用插件前调用 `mermaid.initialize()` 来配置 Mermaid 行为：

```js
import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: false,
  theme: 'default',
  securityLevel: 'loose',
  // 其他 mermaid 选项...
});
```

## 支持的图表类型

- 流程图 (Flowcharts)
- 时序图 (Sequence diagrams)
- 甘特图 (Gantt charts)
- 类图 (Class diagrams)
- 状态图 (State diagrams)
- 实体关系图 (Entity Relationship diagrams)
- 用户旅程图 (User Journey diagrams)
- 饼图 (Pie charts)
- 需求图 (Requirement diagrams)
- Git 图形 (Git graphs)

更多 Mermaid 语法与图表类型，请参考 [Mermaid 官方在线编辑器](https://mermaid.live/)。

## 浏览器支持

本插件适用于所有支持 ES6+ 特性的现代浏览器。它需要 DOM 环境来渲染 Mermaid 图表。

## 性能

插件内置了缓存机制，以提高重复渲染相同 Mermaid 代码时的性能。缓存会自动清理旧条目以防止内存泄漏。

## 贡献指南

我们欢迎贡献！请随时提交 Pull Request。对于重大更改，请先打开 issue 讨论您想要更改的内容。

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启一个 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 作者

Fangjianchao

## 仓库地址

[Gitee 仓库](https://gitee.com/ericfang/markdown-it-mermaid)

## 问题反馈

在 [issue tracker](https://gitee.com/ericfang/markdown-it-mermaid/issues) 上报告错误或请求新功能。

---

让 Markdown 不仅能写文字，还能"画"出逻辑！欢迎 Star ⭐ 和贡献 💡！