Plugins Overview

Extend Marzipan with powerful first-party plugins for tables, diagrams, images, and more.

What are Plugins?

Marzipan plugins are functions that enhance the editor with additional features. They can:

Add toolbar buttons
Insert custom markdown
Render special content
Integrate with external services
Customize the editing experience

Plugin System

How Plugins Work

Plugins are simple functions that receive the editor instance:

type MarzipanPlugin = (editor: MarzipanInstance) => void;

Using Plugins

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

const [editor] = new Marzipan('#editor', {
  toolbar: true,
  plugins: [
    tablePlugin(),
    mermaidPlugin()
  ]
});

First-Party Plugins

Marzipan provides several built-in plugins ready to use:

Built-in Features vs Plugins

Some features like Block Handles are built into Marzipan and configured directly in the editor options, while others are imported as plugins. Both types extend the editor's functionality!

📊 Table Plugins

Three table plugins for different workflows:

tablePlugin - Basic table creation with toolbar button
tableGridPlugin - Visual grid picker (like Word/Excel)
tableGeneratorPlugin - Prompt-based table insertion

import { 
  tablePlugin, 
  tableGridPlugin, 
  tableGeneratorPlugin 
} from '@pinkpixel/marzipan/plugins';

new Marzipan('#editor', {
  plugins: [
    tablePlugin({ defaultColumns: 3, defaultRows: 3 }),
    tableGridPlugin({ maxColumns: 10, maxRows: 10 }),
    tableGeneratorPlugin()
  ]
});

→ Table Plugins Documentation

📈 Mermaid Diagrams

Render beautiful diagrams and flowcharts:

mermaidPlugin - ESM/npm version for production
mermaidExternalPlugin - CDN version for sandboxed environments

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

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

Supports flowcharts, sequence diagrams, class diagrams, state diagrams, and more!

→ Mermaid Documentation

🖼️ Image Plugins

Two plugins for image management:

imagePickerPlugin - Quick URL insertion
imageManagerPlugin - Full management with upload, recents, drag-drop, paste

import { 
  imagePickerPlugin,
  imageManagerPlugin 
} from '@pinkpixel/marzipan/plugins';

new Marzipan('#editor', {
  plugins: [
    imagePickerPlugin(),
    imageManagerPlugin({
      maxRecent: 24,
      uploader: async (file) => {
        // Upload to your server
        const formData = new FormData();
        formData.append('image', file);
        const res = await fetch('/api/upload', { 
          method: 'POST', 
          body: formData 
        });
        return (await res.json()).url;
      }
    })
  ]
});

→ Image Plugins Documentation

🎨 Accent Swatch

Customize editor accent color with visual picker:

import { accentSwatchPlugin } from '@pinkpixel/marzipan/plugins';

new Marzipan('#editor', {
  plugins: [
    accentSwatchPlugin({
      defaults: ['#8b5cf6', '#ef4444', '#10b981', '#3b82f6'],
      max: 12
    })
  ]
});

Features eyedropper support, localStorage persistence, and three color selection methods.

→ Accent Swatch Documentation

🎯 Block Handles

Interactive block manipulation with visual handles:

import { Marzipan } from '@pinkpixel/marzipan';

new Marzipan('#editor', {
  blockHandles: {
    enabled: true,
    showOnHover: true,
    colors: {
      hover: 'rgba(59, 130, 246, 0.1)',
      selected: 'rgba(59, 130, 246, 0.2)',
      handle: 'rgba(59, 130, 246, 0.8)',
    }
  }
});

Features visual handles for selecting, copying, and deleting markdown blocks with mouse and keyboard shortcuts.

→ Block Handles Documentation

Quick Start

1. Import Plugins

import { Marzipan } from '@pinkpixel/marzipan';
import { 
  tablePlugin,
  mermaidPlugin,
  imageManagerPlugin,
  accentSwatchPlugin
} from '@pinkpixel/marzipan/plugins';

2. Configure Plugins

const [editor] = new Marzipan('#editor', {
  toolbar: true,
  theme: 'cave',
  
  plugins: [
    // Tables
    tablePlugin({ defaultColumns: 3, defaultRows: 3 }),
    
    // Diagrams
    mermaidPlugin({ theme: 'dark' }),
    
    // Images
    imageManagerPlugin({ maxRecent: 16 }),
    
    // Customization
    accentSwatchPlugin()
  ]
});

3. Use Features

Plugins add toolbar buttons and features automatically:

Click table button to insert tables
Write mermaid code blocks for diagrams
Drag-drop images onto editor
Click accent button to change colors

Plugin Imports

All plugins can be imported from the main package:

import { 
  // Tables
  tablePlugin,
  tableGridPlugin,
  tableGeneratorPlugin,
  
  // Diagrams
  mermaidPlugin,
  mermaidExternalPlugin,
  
  // Images
  imagePickerPlugin,
  imageManagerPlugin,
  
  // Styling
  accentSwatchPlugin
} from '@pinkpixel/marzipan/plugins';

Or from specific plugin files:

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

Styling Plugins

Some plugins export CSS for styling:

import { 
  imageManagerPlugin,
  imageManagerStyles
} from '@pinkpixel/marzipan/plugins/imageManagerPlugin';

import {
  accentSwatchPlugin,
  accentSwatchStyles
} from '@pinkpixel/marzipan/plugins/accentSwatchPlugin';

import {
  tableGridPlugin,
  tableGridStyles
} from '@pinkpixel/marzipan/plugins/tableGridPlugin';

// Inject styles
const style = document.createElement('style');
style.textContent = `
  ${imageManagerStyles}
  ${accentSwatchStyles}
  ${tableGridStyles}
`;
document.head.appendChild(style);

new Marzipan('#editor', {
  plugins: [
    imageManagerPlugin(),
    accentSwatchPlugin(),
    tableGridPlugin()
  ]
});

Creating Custom Plugins

Create your own plugins easily:

function myCustomPlugin(options = {}) {
  return (editor) => {
    // Access editor instance
    const { container, textarea, updatePreview } = editor;
    
    // Add toolbar button
    const toolbar = container.querySelector('.marzipan-toolbar');
    const button = document.createElement('button');
    button.textContent = options.label || '⭐';
    button.onclick = () => {
      // Insert text at cursor
      const start = textarea.selectionStart;
      const end = textarea.selectionEnd;
      textarea.setRangeText('**bold text**', start, end, 'end');
      updatePreview();
      textarea.focus();
    };
    
    toolbar?.appendChild(button);
  };
}

// Use your plugin
new Marzipan('#editor', {
  plugins: [
    myCustomPlugin({ label: '🌟' })
  ]
});

Plugin Best Practices

Plugin Development

Return a function that receives the editor instance
Accept options for configurability
Clean up resources when needed
Export styles if plugin needs CSS
Document options and usage
Handle errors gracefully
Test across themes and configurations

Complete Example

import { Marzipan } from '@pinkpixel/marzipan';
import { 
  tableGridPlugin,
  tableGridStyles,
  mermaidPlugin,
  imageManagerPlugin,
  imageManagerStyles,
  accentSwatchPlugin,
  accentSwatchStyles
} from '@pinkpixel/marzipan/plugins';

// Inject plugin styles
const style = document.createElement('style');
style.textContent = `
  ${tableGridStyles}
  ${imageManagerStyles}
  ${accentSwatchStyles}
`;
document.head.appendChild(style);

// Create editor with all plugins
const [editor] = new Marzipan('#editor', {
  toolbar: true,
  theme: 'cave',
  
  plugins: [
    // Tables with grid picker
    tableGridPlugin({
      maxColumns: 8,
      maxRows: 8
    }),
    
    // Mermaid diagrams
    mermaidPlugin({
      theme: 'dark'
    }),
    
    // Image management
    imageManagerPlugin({
      maxRecent: 16,
      persistThresholdBytes: 500 * 1024,
      uploader: async (file) => {
        const formData = new FormData();
        formData.append('file', file);
        const res = await fetch('/api/upload', {
          method: 'POST',
          body: formData
        });
        return (await res.json()).url;
      }
    }),
    
    // Accent color picker
    accentSwatchPlugin({
      defaults: ['#8b5cf6', '#ef4444', '#10b981']
    })
  ],
  
  value: `# My Document

With tables, diagrams, and images!
`
});

Plugin Compatibility

All first-party plugins work in:

Chrome/Edge 60+
Firefox 55+
Safari 11+

Some features require newer browsers:

Eyedropper API: Chrome/Edge 95+
Clipboard API: Chrome/Edge 76+, Firefox 87+, Safari 13.1+

Resources

Bakeshop Demo - Live plugin examples
Source Code - Plugin implementations
Contributing - Build your own plugins

Next Steps

📊 Table Plugins →

Learn about table creation plugins

📈 Mermaid Diagrams →

Render beautiful diagrams

🖼️ Image Plugins →

Manage images with drag-drop

🎨 Accent Swatch →

Customize accent colors

Plugins Overview #

What are Plugins? #

Plugin System #

How Plugins Work #

Using Plugins #

First-Party Plugins #

📊 Table Plugins #

📈 Mermaid Diagrams #

🖼️ Image Plugins #

🎨 Accent Swatch #

🎯 Block Handles #

Quick Start #

1. Import Plugins #

2. Configure Plugins #

3. Use Features #

Plugin Imports #

Styling Plugins #

Creating Custom Plugins #

Plugin Best Practices #

Complete Example #

Plugin Compatibility #

Resources #

Next Steps #