GuruDevvv/my-claude-skills / external/mermaid-tools
mermaid-tools
VerifiedExtracts 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.4 KB |
| SKILL.md | skill md | 5.4 KB |
| references/setup_and_troubleshooting.md | markdown | 5.1 KB |
| scripts/extract-and-generate.sh | script | 5.2 KB |
| scripts/extract_diagrams.py | script | 4.9 KB |
| scripts/puppeteer-config.json | config | 356 B |
| КАК_ИСПОЛЬЗОВАТЬ.md | markdown | 512 B |
references/setup_and_troubleshooting.md
View on GitHub# 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] https://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_SKILL_DIR}/scripts/extract-and-generate.sh`
- Python extractor: `${CLAUDE_SKILL_DIR}/scripts/extract_diagrams.py`
- Puppeteer config: `${CLAUDE_SKILL_DIR}/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_SKILL_DIR}/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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |