Beautiful Mermaid Ascii

Beautiful Mermaid ASCII Rendering

Use lukilabs/beautiful-mermaid (a JS library, not a CLI) to turn Mermaid diagrams into terminal-friendly ASCII/Unicode art.

Quick start

Render a Mermaid file:

skills/beautiful-mermaid-ascii/scripts/mermaid-ascii path/to/diagram.mmd

Install a clean mermaid-ascii command on your PATH (symlink into ~/.local/bin by default):

skills/beautiful-mermaid-ascii/scripts/install-mermaid-ascii

Render from stdin:

cat path/to/diagram.mmd | skills/beautiful-mermaid-ascii/scripts/mermaid-ascii

Render the first Mermaid fenced block from Markdown:

skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --md README.md

Select a different fenced block (1-based):

skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --md README.md --block 2

Installation approach (how this skill “deals with installing”)

scripts/mermaid-ascii auto-installs beautiful-mermaid into a writable cache directory (defaults to $XDG_CACHE_HOME/beautiful-mermaid-ascii, or /tmp/beautiful-mermaid-ascii) when needed, then runs the renderer.

If you want a “real” command on your PATH, prefer the symlink installer:

skills/beautiful-mermaid-ascii/scripts/install-mermaid-ascii

You can also install this folder as a local/global npm package (use a writable npm cache if your ~/.npm is not writable):

# from the repo root
NPM_CONFIG_CACHE=/tmp/npm-cache npm install -g --prefix ~/.local ./skills/beautiful-mermaid-ascii

If you already have beautiful-mermaid installed in the current project, run with:

skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --pkg-dir . path/to/diagram.mmd

Troubleshooting

• If installs fail due to permission errors in ~/.npm or ~/Library/Caches, run with a writable cache directory:
• skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --cache-dir /tmp/bm-cache ...
• If output is empty, verify the Mermaid text is valid and starts with a diagram type (flowchart, sequenceDiagram, etc.).
• For multiple diagrams in Markdown, use --list to enumerate fenced blocks and choose one with --block.

Bundled resources

• skills/beautiful-mermaid-ascii/scripts/mermaid-ascii: Shell wrapper that ensures dependencies are available, then renders.
• skills/beautiful-mermaid-ascii/scripts/mermaid-ascii.mjs: Node CLI that extracts Mermaid (raw or from Markdown fences) and calls renderMermaidAscii.
• skills/beautiful-mermaid-ascii/references/notes.md: Small notes about Mermaid inputs and common patterns.

Mermaid Cheat Sheet

Quick reference for common Mermaid patterns.

---

Flowchart (Quick Start)

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Skip]
    C --> E[End]
    D --> E

Directions: TB TD BT LR RL

Shapes:

[rect]  (rounded)  ((circle))  {diamond}  {{hexagon}}
[(cylinder)]  [[subroutine]]  ([stadium])  >asymmetric]

Arrows:

-->      Arrow
---      Line
-.->     Dotted arrow
==>      Thick arrow
--o      Circle end
--x      Cross end
<-->     Bidirectional

With text: A -->|label| B or A -- label --> B

---

Sequence Diagram (Quick Start)

sequenceDiagram
    participant A as Alice
    participant B as Bob

    A->>B: Hello
    B-->>A: Hi there
    A->>+B: Request
    B-->>-A: Response

Arrows:

->      Solid, no head
->>     Solid with head
-->     Dotted, no head
-->>    Dotted with head
-x      Solid with X
-)      Async (open arrow)

Activation: + activates, - deactivates

Blocks:

loop Label        alt Condition       opt Optional
    ...               ...                 ...
end               else                end
                      ...
                  end

par Action 1      critical Section
    ...           option Fallback
and Action 2          ...
    ...           end
end

---

Class Diagram (Quick Start)

classDiagram
    class Animal {
        +String name
        -int age
        +speak()
        #move(dist) int
    }
    Animal <|-- Dog
    Animal <|-- Cat

Visibility: + public, - private, # protected, ~ package

Relationships:

<|--    Inheritance
*--     Composition
o--     Aggregation
-->     Association
..>     Dependency
..|>    Realization

---

State Diagram (Quick Start)

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : start
    Running --> Paused : pause
    Paused --> Running : resume
    Running --> [*] : finish

Special states: [*] (start/end), <<choice>>, <<fork>>, <<join>>

Composite:

state Active {
    [*] --> Running
    Running --> Stopped
}

---

ER Diagram (Quick Start)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

    CUSTOMER {
        int id PK
        string name
    }

Cardinality:

||    Exactly one
o|    Zero or one
|{    One or more
o{    Zero or more

Read: left to right. ||--o{ = one-to-many

---

Gantt (Quick Start)

gantt
    title Project Plan
    dateFormat YYYY-MM-DD

    section Phase 1
    Research    :a1, 2024-01-01, 10d
    Design      :a2, after a1, 7d

    section Phase 2
    Build       :a3, after a2, 14d

Task states: :done, :active, :crit

---

Pie Chart

pie title Market Share
    "Chrome" : 65
    "Firefox" : 15
    "Safari" : 12
    "Other" : 8

---

Mindmap

mindmap
    root((Project))
        Frontend
            React
            CSS
        Backend
            API
            Database

Shapes: [square] (rounded) ((circle)) {{hexagon}}

---

Timeline

timeline
    title Company History
    section Founding
        2020 : Started
        2021 : First product
    section Growth
        2023 : Series A
        2024 : Expansion

---

Quadrant Chart

quadrantChart
    title Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Schedule
    quadrant-3 Delegate
    quadrant-4 Eliminate

    Task A: [0.2, 0.8]
    Task B: [0.7, 0.6]
    Task C: [0.3, 0.3]

---

Git Graph

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop
    commit tag: "v1.0"

---

User Journey

journey
    title User Onboarding
    section Sign Up
        Visit site: 3: User
        Create account: 4: User
    section First Use
        Complete tutorial: 5: User
        Invite team: 2: User, Admin

Score: 1 (frustrated) to 5 (happy)

---

Configuration

Theme (in frontmatter):

---
config:
    theme: forest
---

Theme (inline):

%%{init: {'theme': 'dark'}}%%

Themes: default forest dark neutral base

---

Comments

%% This is a comment

---

Common Patterns

Decision Tree

flowchart TD
    A{Start} --> B{Question 1?}
    B -->|Yes| C{Question 2?}
    B -->|No| D[Result A]
    C -->|Yes| E[Result B]
    C -->|No| F[Result C]

API Flow

sequenceDiagram
    Client->>+Server: POST /api/data
    Server->>DB: INSERT
    DB-->>Server: OK
    Server-->>-Client: 201 Created

System Architecture

flowchart TB
    subgraph Frontend
        UI[Web App]
    end
    subgraph Backend
        API[REST API]
        Worker[Job Queue]
    end
    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI --> API
    API --> DB
    API --> Cache
    API --> Worker
    Worker --> DB

State Machine

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Published : approve
    Review --> Draft : reject
    Published --> Archived : archive
    Archived --> [*]

Mermaid Syntax Reference

Complete syntax reference for all Mermaid diagram types.

Diagram Types Overview

---

1. Flowchart

Direction

flowchart TD    %% Top-Down (default)
flowchart TB    %% Top-Bottom (same as TD)
flowchart BT    %% Bottom-Top
flowchart LR    %% Left-Right
flowchart RL    %% Right-Left

Node Shapes

Links/Arrows

Link Length

Add extra dashes for longer links:

A --> B       %% Normal
A ---> B      %% Longer
A ----> B     %% Even longer

Subgraphs

flowchart TB
    subgraph one[Title One]
        A --> B
    end
    subgraph two[Title Two]
        C --> D
    end
    one --> two

Styling

flowchart LR
    A --> B --> C

    %% Style individual nodes
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#f66,stroke-dasharray: 5 5

    %% Define and apply classes
    classDef green fill:#9f6,stroke:#333
    classDef red fill:#f66,stroke:#333
    class A green
    class B,C red

Comments

%% This is a comment

---

2. Sequence Diagram

Participants

sequenceDiagram
    participant A as Alice
    participant B as Bob
    actor U as User

Participant types:

• participant - Box (default)
• actor - Stick figure
• boundary - System boundary
• control - Control flow
• entity - Data entity
• database - Cylinder
• collections - Stacked boxes
• queue - Queue symbol

Messages

Activations

sequenceDiagram
    Alice->>+John: Request       %% + activates
    John-->>-Alice: Response     %% - deactivates

    %% Or explicit
    activate John
    deactivate John

Notes

Note right of Alice: Text here
Note left of Bob: Text here
Note over Alice: Text here
Note over Alice,Bob: Spans both

Control Flow

%% Loops
loop Every minute
    Alice->>Bob: Ping
end

%% Conditionals
alt Success
    Alice->>Bob: OK
else Failure
    Alice->>Bob: Error
end

%% Optional
opt Extra processing
    Bob->>Alice: Details
end

%% Parallel
par Alice to Bob
    Alice->>Bob: Hello
and Alice to John
    Alice->>John: Hello
end

%% Critical section
critical Establish connection
    Service->>DB: Connect
option Timeout
    Service->>Service: Retry
end

%% Break
break When error occurs
    Service->>Client: Error
end

Highlighting

rect rgb(200, 220, 255)
    A->>B: Inside highlight
end

Autonumber

sequenceDiagram
    autonumber
    Alice->>Bob: First (1)
    Bob->>Alice: Second (2)

---

3. Class Diagram

Basic Class

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
        +move(distance)
    }

Visibility Modifiers

Method Return Types

class MyClass {
    +getAge() int
    +getName() String
    +process(data) bool
}

Relationships

Cardinality

classDiagram
    Customer "1" --> "*" Order : places
    Order "1" --> "1..*" LineItem : contains

Annotations

classDiagram
    class Shape {
        <<interface>>
        +draw()
    }
    class Singleton {
        <<singleton>>
    }
    class Utility {
        <<abstract>>
    }

Namespaces

classDiagram
    namespace Animals {
        class Dog
        class Cat
    }

---

4. State Diagram

Basic States

stateDiagram-v2
    [*] --> Idle                   %% Start state
    Idle --> Running : start
    Running --> Idle : stop
    Running --> [*]                %% End state

State Descriptions

stateDiagram-v2
    state "Waiting for input" as waiting
    [*] --> waiting

Composite States

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Running
        Running --> Paused : pause
        Paused --> Running : resume
    }

    Active --> [*] : quit

Forks and Joins

stateDiagram-v2
    state fork_state <<fork>>
    state join_state <<join>>

    [*] --> fork_state
    fork_state --> State1
    fork_state --> State2
    State1 --> join_state
    State2 --> join_state
    join_state --> [*]

Choice

stateDiagram-v2
    state check <<choice>>

    [*] --> check
    check --> Success : valid
    check --> Failure : invalid

Notes

stateDiagram-v2
    State1 : Description
    note right of State1
        Extended notes here
    end note
    note left of State2 : Short note

Concurrency

stateDiagram-v2
    state Parallel {
        [*] --> A
        --
        [*] --> B
    }

Direction

stateDiagram-v2
    direction LR
    [*] --> A --> B --> [*]

---

5. ER Diagram

Basic Structure

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"

Cardinality

Full Syntax

<entity1> <relationship> <entity2> : <label>

Entity Attributes

erDiagram
    CUSTOMER {
        int id PK
        string name
        string email UK
        date created_at
    }
    ORDER {
        int id PK
        int customer_id FK
        decimal total
        date order_date
    }

Attribute modifiers:

• PK - Primary Key
• FK - Foreign Key
• UK - Unique Key

---

6. Gantt Chart

Basic Structure

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Phase 1
    Task 1          :a1, 2024-01-01, 30d
    Task 2          :a2, after a1, 20d

    section Phase 2
    Task 3          :a3, after a2, 15d

Date Formats

dateFormat YYYY-MM-DD
dateFormat DD-MM-YYYY
dateFormat MM-DD-YYYY

Task Syntax

Task Name    :id, start, duration
Task Name    :id, start, end
Task Name    :id, after otherId, duration

Task States

Done task      :done, t1, 2024-01-01, 10d
Active task    :active, t2, 2024-01-11, 10d
Critical       :crit, t3, 2024-01-21, 10d
Milestone      :milestone, m1, 2024-02-01, 0d

Excludes

gantt
    excludes weekends
    excludes 2024-01-15, 2024-01-16

---

7. Pie Chart

pie title Favorite Pets
    "Dogs" : 45
    "Cats" : 35
    "Fish" : 15
    "Other" : 5

Show Data

pie showData
    "A" : 30
    "B" : 70

---

8. Mindmap

Basic Structure

mindmap
    root((Central Topic))
        Topic A
            Subtopic 1
            Subtopic 2
        Topic B
            Subtopic 3

Node Shapes

mindmap
    root
        Square[Square]
        Rounded(Rounded)
        Circle((Circle))
        Bang))Bang((
        Cloud)Cloud(
        Hexagon{{Hexagon}}

Icons

mindmap
    root((Main))
        Topic::icon(fa fa-book)
        Another::icon(fa fa-star)

Classes

mindmap
    root:::important
        Normal
        Special:::highlight

---

9. Timeline

Basic Structure

timeline
    title History of Events

    section Early Period
        2020 : Event A
             : Event B
        2021 : Event C

    section Recent
        2023 : Event D
        2024 : Event E : Event F

---

10. Quadrant Chart

quadrantChart
    title Reach vs Engagement
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 Promote
    quadrant-2 Review
    quadrant-3 Eliminate
    quadrant-4 Monitor

    Campaign A: [0.3, 0.6]
    Campaign B: [0.7, 0.8]
    Campaign C: [0.2, 0.2]
    Campaign D: [0.8, 0.3]

Values are 0-1 coordinates. Quadrants numbered 1-4 starting top-right, going counter-clockwise.

---

11. Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    branch feature
    commit
    checkout main
    merge feature

Commit Options

gitGraph
    commit id: "abc123"
    commit id: "Normal"
    commit id: "Reverse" type: REVERSE
    commit id: "Highlight" type: HIGHLIGHT
    commit tag: "v1.0"

---

12. User Journey

journey
    title My Daily Routine
    section Morning
        Wake up: 5: Me
        Coffee: 4: Me, Cat
        Commute: 2: Me
    section Work
        Meetings: 3: Me, Team
        Coding: 5: Me

Format: Task: score: actors where score is 1-5 (1=bad, 5=great).

---

Configuration

Frontmatter

---
title: My Diagram
config:
    theme: forest
---
flowchart LR
    A --> B

Themes

• default
• forest
• dark
• neutral
• base

Init Directive

%%{init: {'theme': 'forest', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
flowchart LR
    A --> B

---

Tips for ASCII Rendering

When using beautiful-mermaid for ASCII output:

1. Keep diagrams simple - Complex diagrams may not render well in ASCII 2. Use short labels - Long text may overflow or wrap unexpectedly 3. Prefer LR/TB directions - These render more predictably 4. Avoid nested subgraphs - Stick to single-level subgraphs 5. Test incrementally - Build complex diagrams piece by piece

Notes

Reference Documents

• [mermaid-syntax-reference.md](./mermaid-syntax-reference.md) - Complete syntax for all 17+ diagram types
• [mermaid-cheatsheet.md](./mermaid-cheatsheet.md) - Quick reference with copy-paste examples

Mermaid Inputs

• Mermaid diagrams are plain text that start with a diagram type keyword:
• flowchart LR / flowchart TD
• sequenceDiagram
• classDiagram
• stateDiagram-v2
• erDiagram
• gantt
• pie
• mindmap
• timeline
• quadrantChart
• gitGraph
• journey
• And more...

• If rendering a Markdown file, this skill only extracts triple-backtick blocks fenced with mermaid:

flowchart LR A --> B

Tips for Terminal Previews

• Use a monospace font; Unicode box-drawing characters render best with a font that supports them well
• If diagrams look "squished", try increasing your terminal window width
• Keep diagrams simple for better ASCII rendering
• Use short labels to avoid overflow/wrapping
• Prefer LR (left-right) or TB (top-bottom) directions
• Avoid deeply nested subgraphs
• Test complex diagrams incrementally

Quick Examples

Flowchart

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

Sequence

sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi

State

stateDiagram-v2
    [*] --> Active
    Active --> [*]