mermaid tools
- Repo stars 0
- Author updated Aug 24, 2026, 07:33 AM
- Author repo claude-code-skills
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Env read
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# High-Resolution Output for Presentations
cd "${CLAUDE_SKILL_DIR}/scripts"
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
# 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_SKILL_DIR}/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_SKILL_DIR}/scripts"
./extract-and-generate.sh "<markdown_file>" "<output_directory>"
```
### 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_SKILL_DIR}/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_SKILL_DIR}/scripts"
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
```
### Print-Quality Output
```bash
cd "${CLAUDE_SKILL_DIR}/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_SKILL_DIR}/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_SKILL_DIR}/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.
Sections and files
Listed in source order.
sections -> Overview → Core Workflow → Standard Diagram Extraction and Generation → What the Script Does → Output Files → Advanced Usage
terms -> Parameters · Example · Extracts · Numbers · Generates · Creates · Validates · Available variables
files/cmd -> extract-and-generate.sh · extract_diagrams.py · puppeteer-config.json · scripts/ · <markdown_file> · <output_directory> · <markdown_file_directory>/diagrams · .mmd
body sha256 -> da25cb06df7b
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, andpuppeteer-config.json) in thescripts/directory for portability and reliability.Standard Diagram Extraction and Generation
Extract Mermaid diagrams from a markdown file and generate PNG images using the bundled
extract-and-generate.shscript: Parameters:<markdown_file>: Path to the markdown file containing Mermaid diagrams<output_directory>: (Optional) Directory for output files. Defaults to<markdown_file_directory>/diagramsExample: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
.mmdfiles for each diagram Creates high-resolution PNG images with smart sizing Validates all generated PNG filesOutput Files
For each diagram, the script generates:
01-diagram-name.mmd- Extracted Mermaid code01-diagram-name.png- High-resolution PNG image The numbering ensures diagrams maintain their order from the source document.Custom Dimensions and Scaling
Override default dimensions using environment variables: Available variables:
MERMAID_WIDTH(default: 1200) - Base width in pixelsMERMAID_HEIGHT(default: 800) - Base height in pixelsMERMAID_SCALE(default: 2) - Scale factor for high-resolution output