mermaid2img

v1.0.3

Published

5 days ago

CLI tool to extract and export Mermaid diagrams from Markdown files to PNG/SVG images

0High
0Medium
0Low

gtouck

mermaid diagram export markdown cli svg png

Mermaid Export 🎨

一个强大的命令行工具，用于从 Markdown 文件中提取 Mermaid 图表并导出为 PNG 和 SVG 图片。

English | 简体中文

✨ 特性

批量处理：从单个或多个 Markdown 文件中提取所有 Mermaid 图表
多种格式：导出为 PNG、SVG 或同时导出两种格式
智能命名：灵活的文件名模式（自动、基于标题或基于索引）
冲突解决：通过重命名、覆盖、跳过或报错策略处理已存在的文件
递归处理：支持处理整个目录树及子目录
自定义输出：配置图片尺寸、背景颜色等
并行渲染：控制并发数以优化性能
错误处理：提供详细的错误报告和可操作的建议
预览模式：在不创建文件的情况下预览操作
进度指示：批量操作时提供可视化反馈

📦 安装

前置要求

Node.js：需要 18.0.0 或更高版本。

Linux 用户：需要安装 Chrome 无头渲染所需的系统依赖：

sudo apt-get update
sudo apt-get install -y \
  libnss3 \
  libnspr4 \
  libatk1.0-0 \
  libatk-bridge2.0-0 \
  libcups2 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxrandr2 \
  libgbm1 \
  libasound2

中文/CJK 文本支持（如果你的图表包含中文、日文或韩文字符，此步骤必须执行）：

sudo apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra

sudo yum install -y \
  nss \
  nspr \
  atk \
  at-spi2-atk \
  cups-libs \
  libdrm \
  libxkbcommon \
  libXcomposite \
  libXdamage \
  libXrandr \
  mesa-libgbm \
  alsa-lib

中文/CJK 文本支持：

sudo yum install -y google-noto-sans-cjk-fonts google-noto-serif-cjk-fonts

sudo pacman -S --noconfirm \
  nss \
  nspr \
  atk \
  at-spi2-atk \
  libcups \
  libdrm \
  libxkbcommon \
  libxcomposite \
  libxdamage \
  libxrandr \
  mesa \
  alsa-lib

中文/CJK 文本支持：

sudo pacman -S --noconfirm noto-fonts-cjk

⚠️ 中文用户重要提示：如果导出的图片中中文显示为方框（□□□），请安装上述 CJK 字体包。这是必需的，因为 Linux 最小化安装通常不包含亚洲字体。

全局安装（推荐）

npm install -g mermaid2img

本地安装

npm install mermaid2img

从源码安装

git clone https://github.com/yourusername/mermaid-export.git
cd mermaid-export
npm install
npm run build
npm link

🚀 快速开始

基本用法

从单个 Markdown 文件导出所有图表：

mermaid-export documentation.md
# 或使用简短别名
mmet documentation.md

这将在源文件同目录创建一个 images 目录并生成 PNG 和 SVG 图片（例如，处理 /docs/api.md 时，输出到 /docs/images/）。

使用配置文件

创建 .mermaidrc.json 文件来设置默认选项：

用户级配置（~/.mermaidrc.json）- 所有项目的全局偏好：

{
  "scale": 2,
  "backgroundColor": "transparent",
  "naming": "title"
}

项目级配置（./.mermaidrc.json）- 项目特定设置：

{
  "outputDir": "./diagrams",
  "format": "both",
  "recursive": true
}

然后只需运行：

mmet documentation.md

支持的配置文件名（按优先级搜索）：

.mermaidrc.json
.mermaidrc
mermaid.config.json

配置优先级（从高到低）：

CLI 参数 - 临时覆盖
项目配置 - 项目特定设置（当前目录）
用户配置 - 全局用户偏好（~/.mermaidrc.json）
内置默认值 - 后备值

使用 --no-config 忽略所有配置文件。

指定输出目录

mmet documentation.md -o ./diagrams

仅导出 PNG

mmet documentation.md -f png

处理多个文件

mmet file1.md file2.md file3.md

递归处理目录

mmet ./docs -r

自定义配置

mmet documentation.md \
  --width 1920 \
  --height 1080 \
  --bg-color "#FFFFFF" \
  --naming title \
  --on-conflict rename

--no-config - 忽略配置文件（如果存在）

📖 使用说明

命令语法

mermaid-export [文件...] [选项]
# 或
mmet [文件...] [选项]

参数

[文件...] - 要处理的 Markdown 文件或目录（默认：当前目录）

选项

输出选项

-o, --output <目录> - 图片输出目录（默认：源文件同目录下的 images/）
-f, --format <类型> - 导出格式：png、svg 或 both（默认：both）
--width <像素> - 输出图片宽度（100-10000 像素）
--height <像素> - 输出图片高度（100-10000 像素）
--scale <倍数> - PNG 缩放因子，用于高分辨率显示（1-3，默认：2）
--bg-color <颜色> - 背景颜色：transparent 或十六进制颜色如 #FFFFFF（默认：transparent）

处理选项

-r, --recursive - 递归处理子目录
--max-concurrent <数量> - 最大并发渲染数（1-20，默认：5）
--dry-run - 预览操作而不创建文件

命名选项

--naming <模式> - 文件名模式（默认：auto）
- auto - 如果有标题则使用标题，否则使用索引
- title - 总是使用图表标题（如果缺少标题则报错）
- index - 总是使用源文件名 + 索引（如：doc-diagram-1.png）

冲突解决

--on-conflict <策略> - 如何处理已存在的文件（默认：rename）
- rename - 添加数字后缀（如：diagram-2.png、diagram-3.png）
- overwrite - 替换已存在的文件
- skip - 保留已存在的文件，跳过导出
- error - 抛出错误并停止

日志选项

-v, --verbose - 启用详细日志
-q, --quiet - 仅显示错误信息
-V, --version - 显示版本号
-h, --help - 显示帮助信息

📋 示例

示例 1：单文件导出

从文档文件导出所有图表：

mermaid-export README.md

输入：包含 3 个 Mermaid 图表的 README.md 输出：在 ./images/ 中生成 6 个文件（3 个 PNG + 3 个 SVG）（与 README.md 同目录）

示例 2：自定义输出目录和格式

仅导出 SVG 文件到自定义目录：

mermaid-export architecture.md -o ./docs/diagrams -f svg

示例 3：递归批量处理

处理目录树中的所有 Markdown 文件：

mermaid-export ./documentation -r -o ./exported-diagrams

示例 4：基于标题命名

使用图表标题作为文件名：

mermaid-export design.md --naming title

Markdown 文件：

```mermaid
%% title: 系统架构
graph TD
  A[客户端] --> B[服务器]
```

输出：系统架构.png、系统架构.svg

示例 5：自定义图片尺寸

导出指定尺寸的图片：

mermaid-export flowchart.md --width 1920 --height 1080 --bg-color "#FFFFFF"

示例 6：高分辨率 PNG（适用于视网膜屏幕）

使用 3 倍缩放因子导出 PNG，在高分辨率屏幕上获得清晰的文字效果：

mermaid-export document.md -f png --scale 3

缩放因子指南：

--scale 1 - 标准分辨率（文件最小）
--scale 2 - 高分辨率/视网膜屏幕（默认，推荐）
--scale 3 - 超高分辨率（质量最佳，文件较大）

示例 7：预览模式

预览将要创建的内容而不实际创建文件：

mermaid-export ./docs -r --dry-run

示例 7：使用配置文件

在项目中创建 .mermaidrc.json：

{
  "outputDir": "./documentation/diagrams",
  "format": "png",
  "scale": 3,
  "naming": "title",
  "recursive": true
}

然后不指定选项运行：

mermaid-export ./docs

用 CLI 参数覆盖配置文件设置：

mermaid-export ./docs --format svg --scale 2

完全忽略配置文件：

mermaid-export ./docs --no-config

⚙️ 配置文件

您可以在两个级别创建配置文件来设置默认选项：

配置位置

用户配置（~/.mermaidrc.json）- 全局用户偏好
- 应用于所有项目
- 适合个人默认值（缩放、命名等）
项目配置（./.mermaidrc.json）- 项目特定设置
- 仅应用于当前项目
- 适合团队共享设置
- 覆盖用户配置

支持的文件名

工具按以下顺序搜索配置文件：

.mermaidrc.json
.mermaidrc
mermaid.config.json

配置格式

所有选项都是可选的。只需指定您想要覆盖的值。

{
  "outputDir": "./diagrams",
  "format": "both",
  "scale": 2,
  "width": 1920,
  "height": 1080,
  "backgroundColor": "transparent",
  "naming": "auto",
  "onConflict": "rename",
  "recursive": true,
  "maxConcurrent": 10,
  "verbose": false,
  "quiet": false
}

配置选项

| 选项 | 类型 | 可选值 | 默认值 | 说明 | |------|------|--------|--------|------| | outputDir | string | 任何路径 | "./images" | 图片输出目录 | | format | string | "png", "svg", "both" | "both" | 导出格式 | | scale | number | 1-3 | 2 | PNG 缩放因子 | | width | number | 100-10000 | - | 图片宽度（像素）| | height | number | 100-10000 | - | 图片高度（像素）| | backgroundColor | string | "transparent" 或 "#RRGGBB" | "transparent" | 背景颜色 | | naming | str临时覆盖（最高优先级） 2. 项目配置 - 团队/项目设置（./.mermaidrc.json） 3. 用户配置 - 个人偏好（~/.mermaidrc.json） 4. 内置默认值 - 后备值（最低优先级）

示例

用户配置（~/.mermaidrc.json）- 设置您的个人默认值：

{
  "scale": 3,
  "naming": "title",
  "backgroundColor": "transparent"
}

项目配置（./.mermaidrc.json）- 为此项目覆盖：

{
  "outputDir": "./docs/diagrams",
  "format": "svg",
  "recursive": true
}

优先级顺序

配置按以下顺序解析（优先级从高到低）：

CLI 参数 - 总是覆盖一切
配置文件 - 项目特定的默认值
内置默认值 - 后备值

示例

最小配置（只覆盖需要的）：

{
  "outputDir": "./docs/images",
  "scale": 3
}

生产环境配置（高质量）：

{
  "outputDir": "./public/diagrams",
  "format": "svg",
  "naming": "title",
  "onConflict": "error"
}

开发环境配置（快速迭代）：

{
  "format": "png",
  "scale": 1,
  "maxConcurrent": 10,
  "onConflict": "overwrite"
}

忽略配置文件

使用 --no-config 忽略任何配置文件：

mermaid-export ./docs --no-config

这将只使用 CLI 参数和内置默认值。

🐛 错误处理

工具提供清晰的、可操作的错误消息：

文件未找到

❌ 错误：文件未找到：documentation.md
建议：
  - 检查文件路径
  - 使用 --help 查看示例

Mermaid 语法错误

❌ 错误：documentation.md (第 45 行) 中的 Mermaid 语法错误
  graph TD
    A -> B  ← 无效语法
建议：
  - 检查 Mermaid 语法：https://mermaid.js.org/
  - 使用 '-->' 而不是 '->'

中文字符显示为方框（Linux）

问题：中文/日文/韩文文本在导出的图片中显示为 □□□
解决方案：
  - Ubuntu/Debian: sudo apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra
  - CentOS/RHEL: sudo yum install -y google-noto-sans-cjk-fonts
  - Arch Linux: sudo pacman -S noto-fonts-cjk
  - 查看 README 中的前置要求部分获取完整说明

更多详细的故障排除信息，请参阅 TROUBLESHOOTING.md。

🔍 退出代码

0 - 成功
1 - 一般错误
2 - 无效使用（错误的参数）
66 - 文件未找到
77 - 权限被拒绝

📊 性能

内存：典型工作负载（100+ 个图表）< 500MB
处理：线性时间复杂度 - 随图表数量线性扩展
并发：可配置限制的并行渲染（默认：5）

基准测试（100 个图表）：

处理时间：约 30-60 秒（取决于图表复杂度）
内存使用：峰值约 300MB
输出：200 个文件（100 个 PNG + 100 个 SVG）

🎯 支持的图表类型

流程图（graph、flowchart）
序列图（sequenceDiagram）
类图（classDiagram）
状态图（stateDiagram）
实体关系图（erDiagram）
甘特图（gantt）
饼图（pie）
以及更多！

🤝 贡献

欢迎贡献！详情请参阅 CONTRIBUTING.md。

📄 许可证

MIT 许可证 - 详见 LICENSE。

🙏 致谢

Mermaid.js - 图表生成
Commander.js - CLI 框架
Remark - Markdown 解析
Vitest - 测试框架

📚 资源

常见问题

为什么导出的图片中中文是方框？

这是 Linux 系统缺少中文字体导致的。请安装 CJK 字体包：

# Ubuntu/Debian
sudo apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra

# CentOS/RHEL
sudo yum install -y google-noto-sans-cjk-fonts

# Arch Linux
sudo pacman -S noto-fonts-cjk

详细说明请参阅故障排除指南。

如何在图表中添加标题？

在 Mermaid 代码块中使用特殊注释：

```mermaid
%% title: 我的图表标题
graph TD
  A --> B
```

支持哪些输出格式？

支持 PNG 和 SVG 格式。可以使用 -f 选项选择：

-f png - 仅 PNG
-f svg - 仅 SVG
-f both - 同时生成两种格式（默认）

用 ❤️ 为开发者社区打造