---
name: pretty-mermaid
description: >-
  Render beautiful Mermaid diagrams as SVG or ASCII art using the beautiful-mermaid library. Supports 15+ themes, 5 diagram types (flowchart, sequence, state, class, ER), and ultra-fast rendering. Use when the user asks to render or create Mermaid diagrams, apply themes, batch process diagrams, create ASCII/terminal-friendly diagrams, or visualize architecture, workflows, or data models.
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Pretty Mermaid

Render stunning, professionally-styled Mermaid diagrams with one command. Supports SVG for web/docs and ASCII for terminals.

## Quick Start

### Render a Single Diagram

**From a file:**
```bash
node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --format svg \
  --theme tokyo-night
```

**From user-provided Mermaid code:**
1. Save the code to a `.mmd` file
2. Run the render script with desired theme

### Batch Render Multiple Diagrams

```bash
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./output \
  --format svg \
  --theme dracula \
  --workers 4
```

For detailed batch recipes, see [EXAMPLES.md](references/EXAMPLES.md#batch-rendering-recipes).

### ASCII Output (Terminal-Friendly)

```bash
node scripts/render.mjs \
  --input diagram.mmd \
  --format ascii \
  --use-ascii
```

---

## Workflow Decision Tree

**Step 1: What does the user want?**
- **Render existing Mermaid code** → Go to [Rendering](#rendering-diagrams)
- **Create new diagram** → Go to [Creating](#creating-diagrams)
- **Apply/change theme** → Go to [Theming](#theming)
- **Batch process** → Go to [Batch Rendering](#batch-rendering)

**Step 2: Choose output format**
- **SVG** (web, docs, presentations) → `--format svg`
- **ASCII** (terminal, logs, plain text) → `--format ascii`

**Step 3: Select theme**
- **Dark mode docs** → `tokyo-night` (recommended)
- **Light mode docs** → `github-light`
- **Vibrant colors** → `dracula`
- **See all themes** → Run `node scripts/themes.mjs`

---

## Rendering Diagrams

### From File

When user provides a `.mmd` file or Mermaid code block:

1. **Save to file** (if code block):
   ```bash
   cat > diagram.mmd << 'EOF'
   flowchart LR
       A[Start] --> B[End]
   EOF
   ```

2. **Render with theme**:
   ```bash
   node scripts/render.mjs \
     --input diagram.mmd \
     --output diagram.svg \
     --theme tokyo-night
   ```

3. **Verify output**: SVG → open in browser; ASCII → display in terminal

### Output Formats

**SVG (Scalable Vector Graphics)**
- Best for: Web pages, documentation, presentations
- Usage: `--format svg --output diagram.svg`

**ASCII (Terminal Art)**
- Best for: Terminal output, plain text logs, README files
- Usage: `--format ascii` (prints to stdout)
- Options: `--use-ascii` (pure ASCII), `--padding-x 5`, `--padding-y 5`

### Advanced Options

**Custom colors**, **transparent backgrounds**, and **custom fonts** — see [EXAMPLES.md](references/EXAMPLES.md#custom-color-overrides) for full syntax.

Quick reference:
```bash
# Custom colors (override theme)
--bg "#1a1b26" --fg "#a9b1d6" --accent "#7aa2f7"

# Transparent background
--transparent

# Custom font
--font "JetBrains Mono"
```

---

## Creating Diagrams

### Using Templates

```bash
# List templates
ls assets/example_diagrams/
# flowchart.mmd  sequence.mmd  state.mmd  class.mmd  er.mmd

# Copy and modify
cp assets/example_diagrams/flowchart.mmd my-workflow.mmd
# Edit, then render
node scripts/render.mjs --input my-workflow.mmd --output my-workflow.svg --theme github-dark
```

### Diagram Type Quick Reference

For detailed syntax and best practices, see [DIAGRAM_TYPES.md](references/DIAGRAM_TYPES.md).

| Type | Use For | Syntax Start |
|------|---------|-------------|
| **Flowchart** | Processes, workflows, decision trees | `flowchart LR` |
| **Sequence** | API calls, interactions, message flows | `sequenceDiagram` |
| **State** | Application states, lifecycle, FSM | `stateDiagram-v2` |
| **Class** | Object models, architecture | `classDiagram` |
| **ER** | Database schema, data models | `erDiagram` |

**Minimal examples:**

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

```mermaid
sequenceDiagram
    User->>Server: Request
    Server-->>User: Response
```

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
```

### From User Requirements

1. **Identify diagram type**: Process→Flowchart, API→Sequence, States→State, Objects→Class, Database→ER
2. **Create diagram file** with generated Mermaid code
3. **Render and iterate** — review with user, edit, re-render

---

## Theming

### Available Themes (15 total)

Run `node scripts/themes.mjs` for the full list. For detailed color values and use cases, see [THEMES.md](references/THEMES.md).

**Dark themes:**
| Theme | Best For |
|-------|---------|
| `tokyo-night` ⭐ | Modern dev docs |
| `github-dark` | GitHub-style docs |
| `dracula` | Vibrant, high contrast |
| `nord` | Cool, minimalist |
| `catppuccin-mocha` | Warm, eye-friendly |
| `tokyo-night-storm` | OLED / low light |
| `solarized-dark` | Academic docs |
| `one-dark` | Atom-style |
| `zinc-dark` | Minimal dark |

**Light themes:**
| Theme | Best For |
|-------|---------|
| `github-light` | Clean, professional |
| `zinc-light` | Print-friendly |
| `catppuccin-latte` | Warm, friendly |
| `nord-light` | Cool blue |
| `tokyo-night-light` | Soft light |
| `solarized-light` | Research/academic |

### Apply Theme

```bash
node scripts/render.mjs \
  --input diagram.mmd \
  --output themed.svg \
  --theme tokyo-night
```

---

## Batch Rendering

### Basic Usage

```bash
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme tokyo-night \
  --workers 4
```

- `--workers N` — Parallel rendering (default: 4, use 8 for 10+ diagrams)
- Supports both `svg` and `ascii` formats

For multi-format batch recipes, theme comparison loops, and more — see [EXAMPLES.md](references/EXAMPLES.md#batch-rendering-recipes).

---

## Troubleshooting

### beautiful-mermaid Not Installed
```
Error: Cannot find module 'beautiful-mermaid'
```
Auto-installs on first run. If it fails: `cd /path/to/pretty-mermaid-skill && npm install`

### Invalid Mermaid Syntax
```
Error: Parse error on line 3
```
1. Validate syntax against [DIAGRAM_TYPES.md](references/DIAGRAM_TYPES.md)
2. Test on https://mermaid.live/
3. Common errors: missing spaces in `A --> B`, incorrect node shapes, unclosed brackets

### File Not Found
Verify file path is correct; use absolute path if needed.

---

## Resources

### scripts/
- `render.mjs` — Main rendering script
- `batch.mjs` — Batch processing script
- `themes.mjs` — Theme listing utility

### references/
- [THEMES.md](references/THEMES.md) — Detailed theme reference with color values
- [DIAGRAM_TYPES.md](references/DIAGRAM_TYPES.md) — Comprehensive syntax guide for all diagram types
- [EXAMPLES.md](references/EXAMPLES.md) — Batch recipes, use cases, ASCII examples, custom colors
- [api_reference.md](references/api_reference.md) — beautiful-mermaid API documentation

### assets/
- `example_diagrams/` — Templates: flowchart, sequence, state, class, ER (`.mmd`)

---

## Tips & Best Practices

### Performance
- Batch render for 3+ diagrams (parallel processing)
- Keep diagrams under 50 nodes for fast rendering
- Use ASCII for quick previews

### Quality
- Use `tokyo-night` or `github-dark` for technical docs
- Add `--transparent` for dark/light mode compatibility
- Test theme in target environment before batch rendering

### Workflow
1. Start with templates from `assets/example_diagrams/`
2. Iterate with user feedback
3. Apply theme last
4. Render both SVG (docs) and ASCII (README) if needed

### Accessibility
- Use high-contrast themes for presentations
- Add text labels to all connections
- Avoid color-only information encoding
