mermaid-tools

Original source / Raw SKILL.md

---
name: mermaid-tools
description: Extracts Mermaid diagrams from markdown files and generates high-quality PNG images using bundled scripts. Activates when working with Mermaid diagrams, converting diagrams to PNG, extracting diagrams from markdown, or processing markdown files with embedded Mermaid code.
---

# Mermaid Tools

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

## 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"
```

### What the Script Does

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

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

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

### 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>"
```

### Print-Quality Output

```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.

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

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

## Prerequisites Verification

Before running the script, verify dependencies are installed:

1. **mermaid-cli**: `mmdc --version`
2. **Google Chrome**: `google-chrome-stable --version`
3. **Python 3**: `python3 --version`

If any are missing, consult `references/setup_and_troubleshooting.md` for installation instructions.

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

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

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

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/setup_and_troubleshooting.md

```markdown
# Mermaid Diagram Generation - Setup and Troubleshooting

## Table of Contents
- [Prerequisites](#prerequisites)
- [Script Locations](#script-locations)
- [Features](#features)
- [Environment Variables](#environment-variables)
- [Troubleshooting](#troubleshooting)
- [Validation](#validation)

## Prerequisites

### 1. Node.js and mermaid-cli

Install mermaid-cli globally:
```bash
npm install -g @mermaid-js/mermaid-cli
```

Verify installation:
```bash
mmdc --version
```

### 2. Google Chrome for WSL2

Install Chrome and dependencies:
```bash
# Add Chrome repository
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list

# Update and install Chrome
sudo apt update
sudo apt install -y google-chrome-stable

# Install required dependencies for WSL2
sudo apt install -y libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb fonts-liberation libxml2-utils
```

Verify Chrome installation:
```bash
google-chrome-stable --version
```

### 3. Python 3

The extraction script requires Python 3 (usually pre-installed on Ubuntu):
```bash
python3 --version
```

## Script Locations

The mermaid diagram tools are bundled with this skill in the `scripts/` directory:
- Main script: `~/.claude/skills/mermaid-tools/scripts/extract-and-generate.sh`
- Python extractor: `~/.claude/skills/mermaid-tools/scripts/extract_diagrams.py`
- Puppeteer config: `~/.claude/skills/mermaid-tools/scripts/puppeteer-config.json`

All scripts should be run from the `scripts/` directory to properly locate dependencies.

## Features

### Smart Sizing

The script automatically adjusts diagram dimensions based on filename patterns:

- **Timeline/Gantt charts**: 2400x400 (wide and short)
- **Architecture/System/Caching diagrams**: 2400x1600 (large and detailed)
- **Monitoring/Workflow/Sequence/API diagrams**: 2400x800 (wide for process flows)
- **Default**: 1200x800 (standard size)

### Sequential Numbering

Diagrams are automatically numbered sequentially (01, 02, 03, etc.) in the order they appear in the markdown file.

### High-Resolution Output

Default scale factor is 2x for high-quality output. Can be customized with environment variables.

## Environment Variables

Override default dimensions and scaling:

| Variable | Default | Description |
|----------|---------|-------------|
| `MERMAID_WIDTH` | 1200 | Base width for generated PNGs |
| `MERMAID_HEIGHT` | 800 | Base height for generated PNGs |
| `MERMAID_SCALE` | 2 | Scale factor for high-resolution output |

### Examples

```bash
# Custom dimensions
MERMAID_WIDTH=1600 MERMAID_HEIGHT=1200 ./extract-and-generate.sh "file.md" "output_dir"

# High-resolution mode for presentations
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "file.md" "output_dir"

# Ultra-high resolution for print materials
MERMAID_SCALE=5 ./extract-and-generate.sh "file.md" "output_dir"
```

## Troubleshooting

### Browser Launch Failures

**Symptom**: Errors about Chrome not launching or Puppeteer failures

**Solution**:
1. Verify Chrome is installed: `google-chrome-stable --version`
2. Check Chrome path in script matches: `/usr/bin/google-chrome-stable`
3. Ensure all dependencies are installed (see Prerequisites section 2)
4. Verify puppeteer-config.json exists at the expected location

### Permission Issues

**Symptom**: "Permission denied" when running the script

**Solution**:
```bash
chmod +x ~/.claude/skills/mermaid-tools/scripts/extract-and-generate.sh
```

### No Diagrams Found

**Symptom**: Script reports "No .mmd files found" or "No diagrams extracted"

**Solution**:
1. Verify the markdown file contains Mermaid code blocks (` ```mermaid`)
2. Check the markdown file path is correct
3. Ensure Mermaid code blocks are properly formatted

### Python Extraction Failures

**Symptom**: Errors during the extraction phase

**Solution**:
1. Verify Python 3 is installed: `python3 --version`
2. Check the markdown file encoding (should be UTF-8)
3. Review the markdown file for malformed Mermaid code blocks

### Output Quality Issues

**Symptom**: Generated images are too small or low quality

**Solution**:
Use environment variables to increase dimensions and scale:
```bash
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=3 ./extract-and-generate.sh "file.md" "output_dir"
```

### Diagram-Specific Sizing Issues

**Symptom**: Specific diagram types don't render well with default sizes

**Solution**:
The script has smart sizing for common patterns, but you can override for specific cases:
```bash
# For very wide sequence diagrams
MERMAID_WIDTH=3000 MERMAID_HEIGHT=1000 ./extract-and-generate.sh "file.md" "output_dir"

# For very tall flowcharts
MERMAID_WIDTH=1200 MERMAID_HEIGHT=2400 ./extract-and-generate.sh "file.md" "output_dir"
```

## Validation

The script automatically validates generated PNG files by:
1. Checking file size is non-zero
2. Verifying the file is a valid PNG image
3. Reporting actual dimensions
4. Displaying file size in bytes

Look for ✅ validation messages in the output to confirm successful generation.
```