Mermaid Diagrams in Askimo

Mermaid Diagrams in Askimo

Askimo supports rendering Mermaid diagrams directly in chat responses. Mermaid is a powerful diagramming and charting tool that uses simple text syntax to create various types of diagrams.

What is Mermaid?

Mermaid allows you to create diagrams and visualizations using text and code. It supports many diagram types including:

• Flowcharts - Process flows and decision trees
• Sequence Diagrams - System interactions and workflows
• Class Diagrams - Object-oriented design structures
• State Diagrams - State machines and transitions
• ER Diagrams - Database entity relationships
• Gantt Charts - Project timelines and schedules
• Pie Charts - Data proportions
• And many more!

How Askimo Renders Mermaid Diagrams

Askimo renders Mermaid diagrams locally on your machine to protect your privacy. When an AI response includes a Mermaid diagram:

1. With Mermaid CLI installed: The diagram is rendered as a beautiful, interactive image
2. Without Mermaid CLI: The raw Mermaid syntax text is displayed (you can still copy it to use elsewhere)

Prerequisites

To render Mermaid diagrams in Askimo, you need:

1. Node.js - JavaScript runtime
2. Mermaid CLI - Command-line tool for rendering diagrams

Installation Guide

Step 1: Check if Node.js is Already Installed

Open your terminal and run:

node --version

If you see a version number (e.g., v20.11.0), Node.js is already installed. Skip to Step 3.

If you see an error like command not found, proceed to Step 2.

Step 2: Install Node.js

macOS

Option 1: Using Homebrew (Recommended)

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

Option 2: Download Installer

1. Visit https://nodejs.org/
2. Download the LTS (Long Term Support) version
3. Run the installer and follow the prompts

Windows

Option 1: Download Installer (Recommended)

1. Visit https://nodejs.org/
2. Download the LTS (Long Term Support) version for Windows
3. Run the .msi installer
4. Follow the installation wizard (accept defaults)

Option 2: Using Chocolatey

# Run PowerShell as Administrator
choco install nodejs

Linux

Ubuntu/Debian:

# Using NodeSource repository (recommended for latest version)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora/RHEL/CentOS:

# Using NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs

Arch Linux:

sudo pacman -S nodejs npm

Step 3: Verify Node.js Installation

After installation, verify Node.js and npm are installed:

node --version
npm --version

You should see version numbers for both commands.

Step 4: Install Mermaid CLI

Once Node.js is installed, install Mermaid CLI globally:

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

Note for macOS/Linux users: If you get a permission error, you may need to use sudo:

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

Step 5: Verify Mermaid CLI Installation

Check that Mermaid CLI is installed correctly:

npx @mermaid-js/mermaid-cli --version

You should see the Mermaid CLI version number (e.g., 10.6.1).

Step 6: Restart Askimo

After installing Node.js and Mermaid CLI:

1. Completely quit Askimo (not just close the window)
2. Restart Askimo
3. Mermaid diagrams should now render automatically!

Testing Mermaid Rendering

To test if Mermaid diagrams are working in Askimo, try asking the AI:

Can you create a simple flowchart showing how to make coffee?

Or:

Create an ER diagram for a simple blog database with users, posts, and comments

If everything is set up correctly, you should see a beautifully rendered diagram instead of raw text.

Example Mermaid Diagrams

Flowchart Example

Ask the AI to create diagrams like this:

Prompt: “Create a flowchart for a login process”

flowchart TD
    Start([Start]) --> Input[Enter credentials]
    Input --> Validate{Valid credentials?}
    Validate -->|Yes| Success[Login successful]
    Validate -->|No| Retry{Retry < 3?}
    Retry -->|Yes| Input
    Retry -->|No| Lock[Account locked]
    Success --> End([End])
    Lock --> End

Sequence Diagram Example

Prompt: “Create a sequence diagram for a REST API call”

sequenceDiagram
    participant User
    participant Browser
    participant API
    participant Database

    User->>Browser: Click button
    Browser->>API: POST /api/data
    API->>Database: Query data
    Database-->>API: Return results
    API-->>Browser: JSON response
    Browser-->>User: Display results

ER Diagram Example

Prompt: “Create an ER diagram for an e-commerce database”

erDiagram
    Customer ||--o{ Order : places
    Order ||--o{ OrderItem : contains
    Product ||--o{ OrderItem : "ordered in"

    Customer {
        int id PK
        string name
        string email
    }

    Order {
        int id PK
        date order_date
        int customer_id FK
    }

    Product {
        int id PK
        string name
        decimal price
    }

    OrderItem {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }

Troubleshooting

Diagrams Not Rendering

If diagrams appear as text instead of images:

1. Check Node.js installation:

   node --version

2. Check Mermaid CLI installation:

   npx @mermaid-js/mermaid-cli --version

3. Restart Askimo completely (quit and reopen)

4. Check PATH environment variable:

   • On macOS/Linux: Ensure /usr/local/bin is in your PATH
   • On Windows: Ensure npm global bin directory is in your PATH

Permission Errors on macOS/Linux

If you get EACCES permission errors when installing Mermaid CLI:

Option 1: Use sudo (Quick fix)

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

Option 2: Fix npm permissions (Better long-term solution)

# Create a directory for global installations
mkdir ~/.npm-global

# Configure npm to use the new directory
npm config set prefix '~/.npm-global'

# Add to your PATH (add this line to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Now install without sudo
npm install -g @mermaid-js/mermaid-cli

Mermaid CLI Not Found After Installation

If the installation succeeded but Askimo can’t find the CLI:

1. Find where npm installs global packages:

   npm config get prefix

2. Ensure that directory’s bin folder is in your PATH

3. Restart your terminal and Askimo

Still Having Issues?

If you’re still experiencing problems:

1. Check the Askimo logs (Settings → Advanced → View Logs)
2. Look for error messages related to “Mermaid” or “Node.js”
3. Report the issue on Askimo’s GitHub repository

Privacy & Security

Askimo renders Mermaid diagrams locally on your computer using the Mermaid CLI. This means:

• ✅ Your diagrams never leave your machine
• ✅ No external services are used
• ✅ Complete privacy and security
• ✅ Works offline (after installation)

This is different from many other tools that render diagrams on remote servers.

Advanced Usage

Customizing Diagram Themes

Mermaid diagrams in Askimo automatically adapt to your theme (light/dark mode). The AI can also specify custom themes in the diagram syntax.

Copying Diagrams

Even if you don’t have Mermaid CLI installed, you can:

1. Copy the raw Mermaid syntax from the chat
2. Paste it into online Mermaid editors like Mermaid Live Editor
3. Export as image or SVG

Asking for Specific Diagram Types

Be specific in your prompts to get the diagram type you want:

• “Create a flowchart showing…”
• “Make a sequence diagram for…”
• “Draw an ER diagram representing…”
• “Generate a Gantt chart for…”
• “Create a class diagram with…”

Learn More About Mermaid

• Official Mermaid Documentation
• Mermaid Live Editor - Interactive online editor
• Mermaid Cheat Sheet

Summary

1. Install Node.js from nodejs.org
2. Install Mermaid CLI: npm install -g @mermaid-js/mermaid-cli
3. Restart Askimo
4. Ask AI to create diagrams and enjoy beautiful visualizations!

For questions or issues, visit the GitHub repository.