claude-code-skills-reference/mermaid-tools/references/setup_and_troubleshooting.md

Mermaid Diagram Generation - Setup and Troubleshooting

Table of Contents

• Prerequisites
• Script Locations
• Features
• Environment Variables
• Troubleshooting
• Validation

Prerequisites

1. Node.js and mermaid-cli

Install mermaid-cli globally:

npm install -g @mermaid-js/mermaid-cli

Verify installation:

mmdc --version

2. Google Chrome for WSL2

Install Chrome and dependencies:

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

google-chrome-stable --version

3. Python 3

The extraction script requires Python 3 (usually pre-installed on Ubuntu):

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

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

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:

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:

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