mermaid-it-markdown/README.md

一个markdown-it的插件，用于支持mermaid语法的渲染

# 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)

A plugin that adds **Mermaid diagram support** to [markdown-it](https://github.com/markdown-it/markdown-it).

With this plugin, you can embed Mermaid code blocks directly in your Markdown files and render flowcharts, sequence diagrams, Gantt charts, and more.

📚 **[Documentation & Live Demo](https://fangjc1986.github.io/vue3-blog-vitepress/frontend-components/mermaid-it-markdown.html)** | 🇨🇳 [中文说明文档](https://gitee.com/ericfang/markdown-it-mermaid/blob/master/readme_cn.md)

## Features

- 🚀 Easy integration with markdown-it
- 📊 Support for all Mermaid diagram types (flowcharts, sequence diagrams, Gantt charts, etc.)
- ⚡ Efficient rendering with caching mechanism
- 🔧 Configurable options
- 🌐 Works in browser environments

## Installation

This plugin depends on the official `mermaid` library. Install both packages:

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

> 💡 Note: Make sure to initialize Mermaid in your application (e.g., by calling `mermaid.initialize()` after the page loads).

## Usage

### With markdown-it

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

md.use(mermaidItMarkdown);
```

### With Vue.js and 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);
```

### With VitePress

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

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

## Markdown Syntax Example

Use a fenced code block with the `mermaid` language tag:

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

## API

### Plugin Options

The plugin accepts configuration options when initializing:

```js
md.use(mermaidItMarkdown, {
  // Add custom options here if needed
});
```

### Mermaid Configuration

You can configure Mermaid behavior by calling `mermaid.initialize()` before using the plugin:

```js
import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: false,
  theme: 'default',
  securityLevel: 'loose',
  // other mermaid options...
});
```

## Supported Diagram Types

- Flowcharts
- Sequence diagrams
- Gantt charts
- Class diagrams
- State diagrams
- Entity Relationship diagrams
- User Journey diagrams
- Pie charts
- Requirement diagrams
- Git graphs

For more syntax and diagram types, visit the [Mermaid Live Editor](https://mermaid.live/).

## Browser Support

This plugin works in all modern browsers that support ES6+ features. It requires a DOM environment to render Mermaid diagrams.

## Performance

The plugin includes a built-in caching mechanism to improve performance when rendering the same Mermaid code multiple times. The cache automatically cleans up old entries to prevent memory leaks.

## Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

Fangjianchao

## Repository

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

## Issues

Report bugs or request features on our [issue tracker](https://gitee.com/ericfang/markdown-it-mermaid/issues).

---

Turn your Markdown into visual stories — not just text, but diagrams too!  
⭐ Star the repo if you find it useful! Contributions welcome! 💡