Skill 091

Mermaid Creator

Create professional diagrams using Mermaid syntax for documentation, architecture design, and data modeling.

Workflow

1. Choose diagram type - Select the appropriate diagram based on what needs to be visualized
2. Create .mmd file - Write Mermaid syntax in a .mmd file
3. Validate syntax - Check syntax is correct (Mermaid CLI will report errors)
4. Convert to SVG (optional) - Generate SVG for embedding in presentations or documents

Diagram Type Selection

Choose the right diagram type for your use case:

Load references as needed: Each reference file contains syntax, patterns, examples, and best practices for that diagram type.

Quick Start Examples

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server
    participant DB

    Client->>Server: Request
    Server->>DB: Query
    DB-->>Server: Data
    Server-->>Client: Response

Class Diagram

classDiagram
    class User {
        +String name
        +String email
        +login()
    }

    class Post {
        +String title
        +String content
        +publish()
    }

    User "1" --> "*" Post : creates

Example Files

The skill includes ready-to-use .mmd example files in assets/examples/ that can be copied and modified:

assets/examples/
├── flowchart/          # 10 flowchart examples
│   ├── basic.mmd
│   ├── node-shapes.mmd
│   ├── connections.mmd
│   ├── process-flow.mmd
│   ├── decision-tree.mmd
│   └── ...
├── sequence/           # 12 sequence diagram examples
│   ├── basic.mmd
│   ├── rest-api.mmd
│   ├── authentication-flow.mmd
│   └── ...
├── class/              # 13 class diagram examples
│   ├── basic.mmd
│   ├── inheritance.mmd
│   ├── interface.mmd
│   └── ...
├── state/              # 13 state diagram examples
│   ├── basic.mmd
│   ├── order-processing.mmd
│   ├── authentication.mmd
│   └── ...
├── er/                 # 10 ER diagram examples
│   ├── basic.mmd
│   ├── blog-system.mmd
│   ├── ecommerce.mmd
│   └── ...
└── other/              # 16 other diagram type examples
    ├── gantt-basic.mmd
    ├── pie-basic.mmd
    ├── git-feature-branch.mmd
    ├── journey-shopping.mmd
    ├── quadrant-basic.mmd
    ├── timeline-basic.mmd
    └── ...

Usage: Copy example files as templates for your diagrams. All examples are tested and ready to use with the Mermaid CLI.

Mermaid CLI

Installation

npm install -g @mermaid-js/mermaid-cli

Convert to SVG

mmdc -i diagram.mmd -o diagram.svg

Batch Conversion

mmdc -i input1.mmd -i input2.mmd -o output/

With Configuration

mmdc -i diagram.mmd -o diagram.svg -t dark -b transparent

Options:

• -t - Theme (default, dark, forest, neutral)
• -b - Background color or transparent
• -w - Width
• -H - Height

Best Practices

General Guidelines

• Choose the right diagram type - Match the diagram to the information structure
• Keep it simple - Split complex diagrams into multiple focused diagrams
• Use descriptive labels - Avoid abbreviations unless well-known
• Be consistent - Use consistent naming and styling within a diagram
• Validate syntax - Run through Mermaid CLI to catch errors early

For Documentation

• Create separate .mmd files for each diagram
• Store diagrams near the documentation they support
• Include comments in complex diagrams using %% for Mermaid comments
• Generate SVG for static documentation
• Commit both .mmd source and generated SVG

For Presentations

• Use high contrast colors for visibility
• Keep text large and readable
• Test diagram rendering at presentation size
• Use transparent background to match slide themes
• Prefer SVG over PNG for crisp rendering

Performance

• Large diagrams (>50 nodes) may render slowly
• Split large flowcharts using off-page connectors
• For ER diagrams with many entities, show only relevant relationships
• Consider using subgraphs to organize complex diagrams

Common Patterns

Decision Logic

Use flowcharts with diamond decision nodes:

flowchart TD
    Input[Get Input] --> Validate{Valid?}
    Validate -->|Yes| Process[Process]
    Validate -->|No| Error[Error]

System Interactions

Use sequence diagrams for temporal interactions:

sequenceDiagram
    User->>System: Action
    System->>Database: Query
    Database-->>System: Result
    System-->>User: Response

Data Models

Use ER diagrams for database schemas or class diagrams for object models.

Process Workflows

Use state diagrams for state machines or flowcharts for process flows.

Troubleshooting

Syntax Errors

Run mmdc -i file.mmd -o output.svg to see specific error messages.

Common issues:

• Missing spaces around arrows (A-->B should be A --> B in some contexts)
• Unclosed quotes in labels
• Invalid characters in IDs (use alphanumeric + underscore)
• Wrong diagram type declaration

Rendering Issues

• Check Mermaid CLI version: mmdc --version
• Update to latest: npm install -g @mermaid-js/mermaid-cli@latest
• Try different themes if elements overlap
• Reduce diagram complexity

SVG Quality

• Use mmdc -w 1920 for high-resolution output
• Set background to transparent for flexible embedding
• Test generated SVG in target environment

Advanced Features

Most diagram types support:

• Styling: Custom colors, fonts, and borders
• Subgraphs/Grouping: Organize related elements
• Notes: Add explanatory text
• Direction: Change layout orientation
• Classes: Reusable style definitions

See individual diagram reference files for syntax and examples.