mermaid-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Tools

Mermaid 工具

Overview

概述

This skill enables extraction of Mermaid diagrams from markdown files and generation of high-quality PNG images. The skill bundles all necessary scripts (

extract-and-generate.sh

extract_diagrams.py

, and

puppeteer-config.json

) in the

scripts/

directory for portability and reliability.

本技能支持从Markdown文件中提取Mermaid图表，并生成高质量PNG图片。该技能将所有必要的脚本（

extract-and-generate.sh

、

extract_diagrams.py

和

puppeteer-config.json

）捆绑在

scripts/

目录中，以实现可移植性和可靠性。

Core Workflow

核心工作流

Standard Diagram Extraction and Generation

标准图表提取与生成

Extract Mermaid diagrams from a markdown file and generate PNG images using the bundled

extract-and-generate.sh

script:

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Parameters:

```
<markdown_file>
```
: Path to the markdown file containing Mermaid diagrams

<output_directory>

: (Optional) Directory for output files. Defaults to

<markdown_file_directory>/diagrams

Example:

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "/path/to/document.md" "/path/to/output"

使用捆绑的

extract-and-generate.sh

脚本从Markdown文件中提取Mermaid图表并生成PNG图片：

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

参数：

```
<markdown_file>
```
：包含Mermaid图表的Markdown文件路径

<output_directory>

：（可选）输出文件目录，默认为

<markdown_file_directory>/diagrams

示例：

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "/path/to/document.md" "/path/to/output"

What the Script Does

脚本功能说明

Extracts all Mermaid code blocks from the markdown file
Numbers them sequentially (01, 02, 03, etc.) in order of appearance
Generates
```
.mmd
```
files for each diagram
Creates high-resolution PNG images with smart sizing
Validates all generated PNG files

提取：从Markdown文件中提取所有Mermaid代码块
编号：按出现顺序为图表依次编号（01、02、03等）
生成：为每个图表创建
```
.mmd
```
文件
创建：生成具有智能尺寸的高分辨率PNG图片
验证：验证所有生成的PNG文件

Output Files

输出文件

For each diagram, the script generates:

```
01-diagram-name.mmd
```
- Extracted Mermaid code
```
01-diagram-name.png
```
- High-resolution PNG image

The numbering ensures diagrams maintain their order from the source document.

对于每个图表，脚本会生成：

```
01-diagram-name.mmd
```
- 提取的Mermaid代码
```
01-diagram-name.png
```
- 高分辨率PNG图片

编号可确保图表与源文档中的顺序保持一致。

Advanced Usage

高级用法

Custom Dimensions and Scaling

自定义尺寸与缩放

Override default dimensions using environment variables:

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=1600 MERMAID_HEIGHT=1200 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Available variables:

```
MERMAID_WIDTH
```
(default: 1200) - Base width in pixels
```
MERMAID_HEIGHT
```
(default: 800) - Base height in pixels
```
MERMAID_SCALE
```
(default: 2) - Scale factor for high-resolution output

使用环境变量覆盖默认尺寸：

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=1600 MERMAID_HEIGHT=1200 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

可用变量：

```
MERMAID_WIDTH
```
（默认值：1200）- 基础宽度（像素）
```
MERMAID_HEIGHT
```
（默认值：800）- 基础高度（像素）
```
MERMAID_SCALE
```
（默认值：2）- 高分辨率输出的缩放因子

High-Resolution Output for Presentations

演示用高分辨率输出

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Print-Quality Output

印刷质量输出

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_SCALE=5 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

bash

cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_SCALE=5 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Smart Sizing Feature

智能尺寸功能

The script automatically adjusts dimensions based on diagram type (detected from filename):

Timeline/Gantt: 2400×400 (wide and short)
Architecture/System/Caching: 2400×1600 (large and detailed)
Monitoring/Workflow/Sequence/API: 2400×800 (wide for process flows)
Default: 1200×800 (standard size)

Context-aware naming in the extraction process helps trigger appropriate smart sizing.

脚本会根据图表类型（从文件名检测）自动调整尺寸：

时间线/Gantt：2400×400（宽短型）
架构/系统/缓存：2400×1600（大型详细型）
监控/工作流/序列/API：2400×800（流程流宽型）
默认：1200×800（标准尺寸）

提取过程中的上下文感知命名有助于触发相应的智能尺寸调整。

Important Principles

重要原则

Use Bundled Scripts

使用捆绑脚本

CRITICAL: Use the bundled

extract-and-generate.sh

script from this skill's

scripts/

directory. All necessary dependencies are bundled together.

关键注意事项：请使用本技能

scripts/

目录中捆绑的

extract-and-generate.sh

脚本。所有必要的依赖项均已捆绑在一起。

Change to Script Directory

切换到脚本目录

Run the script from its own directory to properly locate dependencies (

extract_diagrams.py

and

puppeteer-config.json

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Running the script without changing to the scripts directory first may fail due to missing dependencies.

请在脚本自身的目录中运行脚本，以正确定位依赖项（

extract_diagrams.py

和

puppeteer-config.json

）：

bash

cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

如果未先切换到脚本目录就运行脚本，可能会因缺少依赖项而失败。

Prerequisites Verification

依赖项验证

Before running the script, verify dependencies are installed:

mermaid-cli:
```
mmdc --version
```
Google Chrome:
```
google-chrome-stable --version
```
Python 3:
```
python3 --version
```

If any are missing, consult

references/setup_and_troubleshooting.md

for installation instructions.

运行脚本前，请验证依赖项已安装：

mermaid-cli：
```
mmdc --version
```
Google Chrome：
```
google-chrome-stable --version
```
Python 3：
```
python3 --version
```

如果有任何依赖项缺失，请查阅

references/setup_and_troubleshooting.md

获取安装说明。

Troubleshooting

故障排除

For detailed troubleshooting guidance, refer to

references/setup_and_troubleshooting.md

, which covers:

Browser launch failures
Permission issues
No diagrams found
Python extraction failures
Output quality issues
Diagram-specific sizing problems

Quick fixes for common issues:

Permission denied:

bash

chmod +x ~/.claude/skills/mermaid-tools/scripts/extract-and-generate.sh

Low quality output:

bash

MERMAID_SCALE=3 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Chrome/Puppeteer errors: Verify all WSL2 dependencies are installed (see references for full list).

如需详细的故障排除指南，请参阅

references/setup_and_troubleshooting.md

，其中涵盖：

浏览器启动失败
权限问题
未找到图表
Python提取失败
输出质量问题
图表特定尺寸问题

常见问题的快速修复：

权限被拒绝：

bash

chmod +x ~/.claude/skills/mermaid-tools/scripts/extract-and-generate.sh

输出质量低：

bash

MERMAID_SCALE=3 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Chrome/Puppeteer错误： 请验证所有WSL2依赖项已安装（请参阅参考文档获取完整列表）。

Bundled Resources

捆绑资源

scripts/

This skill bundles all necessary scripts for Mermaid diagram generation:

extract-and-generate.sh - Main script that orchestrates extraction and PNG generation
extract_diagrams.py - Python script for extracting Mermaid code blocks from markdown
puppeteer-config.json - Chrome/Puppeteer configuration for WSL2 environment

All scripts must be run from the

scripts/

directory to properly locate dependencies.

本技能捆绑了生成Mermaid图表所需的所有脚本：

extract-and-generate.sh - 协调提取和PNG生成的主脚本
extract_diagrams.py - 从Markdown中提取Mermaid代码块的Python脚本
puppeteer-config.json - 适用于WSL2环境的Chrome/Puppeteer配置

所有脚本必须从

scripts/

目录运行，才能正确定位依赖项。

references/setup_and_troubleshooting.md

Comprehensive reference documentation including:

Complete prerequisite installation instructions
Detailed environment variable reference
Extensive troubleshooting guide
WSL2-specific Chrome dependency setup
Validation procedures

Load this reference when dealing with setup issues, installation problems, or advanced customization needs.

全面的参考文档，包括：

完整的依赖项安装说明
详细的环境变量参考
详尽的故障排除指南
WSL2特定的Chrome依赖项设置
验证流程

在遇到设置问题、安装问题或需要高级自定义时，请查阅此参考文档。