Marzipan

Appearance

Return to top
On this page

Mermaid Diagrams

Render beautiful diagrams and flowcharts directly in your markdown using Mermaid.

Overview

Marzipan provides two Mermaid plugins for different deployment scenarios:

PluginLoad MethodBest For
mermaidPluginESM importProduction apps, bundled projects
mermaidExternalPluginCDN scriptSandboxed environments, quick prototypes

Both plugins render Mermaid diagrams inline in the preview:

markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Nothing]
    C --> E[End]
    D --> E
```

Mermaid Plugin (ESM)

Load Mermaid from npm/ESM for production use.

Installation

First, install Mermaid:

bash
npm install mermaid

Then import the plugin:

ts
import { Marzipan } from '@pinkpixel/marzipan';
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

new Marzipan('#editor', {
  plugins: [mermaidPlugin()]
});

Options

ts
interface MermaidPluginOptions {
  theme?: 'default' | 'dark' | 'forest' | 'neutral';
  config?: MermaidConfig;  // Full Mermaid configuration object
}

Usage Examples

Basic Usage:

ts
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

new Marzipan('#editor', {
  plugins: [mermaidPlugin()]
});

With Dark Theme:

ts
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

new Marzipan('#editor', {
  theme: 'cave',
  plugins: [
    mermaidPlugin({
      theme: 'dark'
    })
  ]
});

Custom Configuration:

ts
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

new Marzipan('#editor', {
  plugins: [
    mermaidPlugin({
      config: {
        theme: 'dark',
        flowchart: {
          curve: 'basis',
          padding: 20
        },
        sequence: {
          diagramMarginX: 50,
          diagramMarginY: 10
        }
      }
    })
  ]
});

Features

  • ✅ Lazy loads Mermaid library
  • ✅ Renders diagrams in preview
  • ✅ Supports all Mermaid diagram types
  • ✅ Configurable themes
  • ✅ Production-ready (bundled with your app)
  • ✅ Works offline

Mermaid External Plugin (CDN)

Load Mermaid from CDN - perfect for sandboxed environments.

Installation

ts
import { mermaidExternalPlugin } from '@pinkpixel/marzipan/plugins/mermaidExternal';

new Marzipan('#editor', {
  plugins: [mermaidExternalPlugin()]
});

Options

ts
interface MermaidExternalOptions {
  theme?: 'default' | 'dark' | 'forest' | 'neutral';
  cdnUrl?: string;  // Custom CDN URL
}

Usage Examples

Basic Usage:

ts
import { mermaidExternalPlugin } from '@pinkpixel/marzipan/plugins/mermaidExternal';

new Marzipan('#editor', {
  plugins: [mermaidExternalPlugin()]
});

Custom CDN:

ts
import { mermaidExternalPlugin } from '@pinkpixel/marzipan/plugins/mermaidExternal';

new Marzipan('#editor', {
  plugins: [
    mermaidExternalPlugin({
      theme: 'dark',
      cdnUrl: 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js'
    })
  ]
});

Features

  • ✅ No npm dependency required
  • ✅ Loads from CDN automatically
  • ✅ Perfect for sandboxed playgrounds
  • ✅ Lighter bundle size
  • ✅ Same rendering quality

When to Use External Plugin

Choose mermaidExternalPlugin when:

  • Building sandboxed code editors
  • Creating quick prototypes
  • Reducing bundle size is critical
  • CDN access is reliable
  • You don't need offline support

Supported Diagram Types

Mermaid supports many diagram types:

Flowchart

markdown
```mermaid
graph LR
    A[Square Rect] --> B((Circle))
    A --> C(Round Rect)
    B --> D{Decision}
    C --> D
```

Sequence Diagram

markdown
```mermaid
sequenceDiagram
    Alice->>John: Hello John!
    John-->>Alice: Great!
    Alice-)John: See you later!
```

Class Diagram

markdown
```mermaid
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    class Duck{
        +String beakColor
        +swim()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
```

State Diagram

markdown
```mermaid
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

Entity Relationship

markdown
```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

Gantt Chart

markdown
```mermaid
gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
```

Pie Chart

markdown
```mermaid
pie title Pets
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
```

Git Graph

markdown
```mermaid
gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop
```

Theme Options

Built-in Mermaid themes:

Default Theme

ts
mermaidPlugin({ theme: 'default' })

Light theme with blue/green colors.

Dark Theme

ts
mermaidPlugin({ theme: 'dark' })

Dark background, perfect for cave theme.

Forest Theme

ts
mermaidPlugin({ theme: 'forest' })

Green-focused color scheme.

Neutral Theme

ts
mermaidPlugin({ theme: 'neutral' })

Grayscale, professional look.

Complete Example

ts
import { Marzipan } from '@pinkpixel/marzipan';
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

const [editor] = new Marzipan('#editor', {
  toolbar: true,
  theme: 'cave',
  
  plugins: [
    mermaidPlugin({
      theme: 'dark',
      config: {
        flowchart: {
          curve: 'basis',
          padding: 20
        }
      }
    })
  ],
  
  value: `# Project Flow

Here's our development workflow:

\`\`\`mermaid
graph TD
    A[Planning] --> B[Development]
    B --> C{Tests Pass?}
    C -->|Yes| D[Deploy]
    C -->|No| B
    D --> E[Monitor]
    E --> F{Issues?}
    F -->|Yes| B
    F -->|No| G[Done]
\`\`\`
`
});

Matching Editor Themes

Coordinate Mermaid theme with Marzipan theme:

ts
import { Marzipan } from '@pinkpixel/marzipan';
import { mermaidPlugin } from '@pinkpixel/marzipan/plugins/mermaidPlugin';

// Determine theme based on user preference
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

new Marzipan('#editor', {
  theme: isDark ? 'cave' : 'solar',
  plugins: [
    mermaidPlugin({
      theme: isDark ? 'dark' : 'default'
    })
  ]
});

Performance Tips

Optimization

  1. Lazy loading - Both plugins lazy-load Mermaid
  2. Debounce updates - Diagrams re-render on content change
  3. Simple diagrams - Complex diagrams slow down preview
  4. CDN for prototypes - Use external plugin for quick tests

Large Diagrams

Very large or complex Mermaid diagrams can slow down the preview. Consider:

  • Breaking into smaller diagrams
  • Using static images for very complex flows
  • Debouncing preview updates

Browser Compatibility

Mermaid plugins work in:

  • Chrome/Edge 60+
  • Firefox 55+
  • Safari 11+

Troubleshooting

Diagrams Not Rendering

  1. Check console for errors
  2. Verify Mermaid syntax is correct
  3. Ensure plugin is loaded before editor creation
  4. Try external plugin if ESM version fails

Theme Not Applying

ts
// Ensure theme is set in config
mermaidPlugin({
  theme: 'dark'  // Not 'config.theme'
})

CDN Loading Fails

ts
// Specify custom CDN
mermaidExternalPlugin({
  cdnUrl: 'https://unpkg.com/mermaid@latest/dist/mermaid.min.js'
})

Resources

See Also

Released under the Apache 2.0 License

Made with ❤️ by Pink Pixel