Mermaid ASCII Diagrams

Render Mermaid diagrams as ASCII/Unicode art and embed them inline in markdown documents. Uses beautiful-mermaid for high-quality terminal-friendly output.

When to Use

• Writing documentation, proposals, technical specs, or design docs
• Any markdown document where a visual diagram would clarify architecture, flows, or relationships
• During doc-coauthoring when explaining system design, data flows, or decision trees
• When you need diagrams that render in plain text (terminals, code reviews, markdown files)

Supported Diagram Types

How to Render

The render script lives at ~/.claude/skills/mermaid-ascii/beauti-diagram/scripts/render.mjs and requires bun.

Write mermaid to a temp file, then render:

# Write mermaid syntax to temp file
cat <<'EOF' > /tmp/diagram.mmd
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]
EOF

# Render to ASCII
bun ~/.claude/skills/mermaid-ascii/beauti-diagram/scripts/render.mjs --file /tmp/diagram.mmd

Or pipe directly:

echo 'graph LR; A[Input] --> B[Process] --> C[Output]' | bun ~/.claude/skills/mermaid-ascii/beauti-diagram/scripts/render.mjs

Then embed the output in a markdown code block:

### System Architecture

```
┌───────┐     ┌─────────┐     ┌────────┐
│       │     │         │     │        │
│ Input ├────►│ Process ├────►│ Output │
│       │     │         │     │        │
└───────┘     └─────────┘     └────────┘
```

Workflow in Documents

1. Identify where a diagram would help the reader understand the content
2. Write valid Mermaid syntax for the diagram
3. Render using the render script via Bash tool
4. Embed only the ASCII output in a fenced code block in the document
5. Do NOT include the original Mermaid source code or HTML comments in the document — only the rendered ASCII result goes in the final output. Include Mermaid source only if the user explicitly asks for it.

Quick Mermaid Syntax Reference

Flowchart

graph TD
  A[Rectangle] --> B{Diamond/Decision}
  B -->|Label| C(Rounded)
  B --> D([Stadium])
  C --> E[(Database)]

Directions: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Sequence Diagram

sequenceDiagram
  participant A as Client
  participant B as Server
  A->>B: Request
  B-->>A: Response
  A->>B: Another call
  Note over A,B: Bidirectional note

State Diagram

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing: start
  Processing --> Done: complete
  Processing --> Error: fail
  Error --> Idle: retry
  Done --> [*]

Class Diagram

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound()
  }
  Animal <|-- Dog
  Animal <|-- Cat

ER Diagram

erDiagram
  USER ||--o{ POST : writes
  POST ||--|{ COMMENT : has
  USER }|--|| PROFILE : has

Common Mistakes

• Missing bun: The render script requires bun runtime (TypeScript support). Install via curl -fsSL https://bun.sh/install | bash
• Missing dependencies: Run cd ~/.claude/skills/mermaid-ascii/beauti-diagram && bun install if the render fails with import errors
• Semicolons in single-line: Single-line mermaid uses ; as separator: graph LR; A --> B; B --> C
• Multiline needs proper newlines: Pipe multiline syntax via heredoc or temp file, not as a single quoted string