MindMapsMD 🧠

A fast markdown-based mindmap editor that transforms your markdown files into interactive visual mindmaps with cross-file linking, inline editing, and real-time updates.

All it takes is to run npx mindmapsmd to start!

Features ✨

The Editor is designed with speed in mind and it scales to hundreds of nodes.

• Markdown-based: Your mindmaps are stored as readable markdown files
• Inline editing: Edit nodes directly in the mindmap view
• Real-time updates: Changes to files are instantly reflected in the mindmap
• Rich customization: Add colors, icons, and metadata to nodes
• Auto-save: Changes are automatically saved as you edit
• File browser: Browse and manage your markdown files
• Keyboard shortcuts: Efficient navigation and editing
• Cross-file linking: Connect nodes across different files with [[filename.md]] syntax
• Task Management: Checking off items to use as your checklist
• Export: export maps as SVG, PNG, and PDF

Installation

Using npx (recommended)

No installation needed! Just run:

npx mindmapsmd

Global installation

npm install -g mindmapsmd

Usage

Start the server

# Run in current directory
npx mindmapsmd

# Specify a directory
npx mindmapsmd -d ./my-notes

# Use a custom port
npx mindmapsmd -p 8080

# With global installation
mindmapsmd -d ./my-notes -p 8080

Command-line options

• -d, --dir <path>: Directory to watch for markdown files (default: current directory)
• -p, --port <number>: Port to run the server on (default: 6789)
• -h, --help: Display help information
• -V, --version: Display version number

Integration Examples 🔧

Want to integrate MindmapMD into your own application? The MindmapEditorWrapper component provides a clean API for external usage with different storage adapters.

Basic Integration with In-Memory Storage

import React, { useRef } from 'react';
import { MindmapEditorWrapper, MemoryStorageAdapter } from 'mindmapsmd';
import type { MindmapEditorRef } from 'mindmapsmd';

function MyApp() {
  const editorRef = useRef<MindmapEditorRef>(null);
  const storageAdapter = new MemoryStorageAdapter();
  
  return (
    <MindmapEditorWrapper
      ref={editorRef}
      filename="my-mindmap.md"
      storageAdapter={storageAdapter}
      content="# My Mindmap\n\n- Topic 1\n  - Subtopic A\n  - Subtopic B"
      onSave={async (content) => console.log('Saved:', content)}
      onChange={(content) => console.log('Changed:', content)}
      layoutMode="balanced"
      features={{
        fileMenu: true,
        autoSave: true,
        export: true,
        comments: true
      }}
    />
  );
}

Storage Adapters

MindmapMD supports different storage adapters for various use cases:

• MemoryStorageAdapter: In-memory storage for demos and testing
• LocalStorageAdapter: File system storage for desktop applications
• ApiStorageAdapter: REST API storage for web applications (custom implementation needed)

Advanced Configuration

// Full feature configuration
const features = {
  fileMenu: true,        // Show file operations menu
  autoSave: true,        // Enable automatic saving
  comments: true,        // Enable node comments
  export: true,          // Enable SVG/PNG/PDF export
  sharing: false,        // Disable sharing features
  collaboration: false   // Disable real-time collaboration
};

// Collaboration setup (optional)
const collaboration = {
  enabled: true,
  websocketUrl: 'ws://localhost:3001',
  userId: 'user123',
  userName: 'John Doe'
};

Programmatic Control

const editorRef = useRef<MindmapEditorRef>(null);

// Control the editor programmatically
const handleExport = async () => {
  const blob = await editorRef.current?.exportAs('svg');
  // Handle the exported blob
};

const handleSetContent = () => {
  editorRef.current?.setContent('# New Content\n\n- Fresh start');
};

// Other available methods:
// editorRef.current?.undo()
// editorRef.current?.redo()
// editorRef.current?.centerView()
// editorRef.current?.zoomIn()
// editorRef.current?.expandAll()

📚 Complete Examples

For comprehensive examples including TypeScript usage, multiple instances, and advanced configurations, see:

🔗 examples/memory-storage-example.html

This interactive example page demonstrates:

• Basic setup with MemoryStorageAdapter
• Advanced feature configuration
• Programmatic control via refs
• Multiple editor instances
• Full TypeScript integration
• Event handling and callbacks

Markdown Syntax

Basic node structure

- {#root}Root Node
  - {#child1}First Child
  - {#child2}Second Child
    - {#grandchild}Grandchild Node

Node metadata

Node can have more bells and whistles.

- {#node1|color:#fee2e2|icon:🚀|completed}Task Node

Boundaries

Add a visual boundary around a node and all its children:

- {#group1|boundary:#3b82f6}Group with Blue Boundary
  - Child nodes will be inside the boundary
  - All descendants are included

Available boundary colors:

• boundary:#3b82f6 - Blue
• boundary:#10b981 - Green
• boundary:#ef4444 - Red
• boundary:#f59e0b - Orange
• boundary:#8b5cf6 - Purple
• boundary:#ec4899 - Pink

Special sections

In order to not clutter up the main mindmap, additional data are separated into sub-sections. Currently Links, Notes, map options are supported.

## Comments
- #node1: This is a comment for node1

## Links
### #node1
- [Google](https://google.com)
- [Documentation](https://docs.example.com)


## Mindmap Options
- horizontalSpacing: 300
- verticalSpacing: 120
- layoutMode: balanced

Keyboard Shortcuts

The Mindmap Editor and Viewer support keyboard navigations and interactions to let you quickly work on the contents.

Navigation

• Arrow keys: Navigate between nodes
• Space: Toggle collapse/expand
• Shift+Space: Toggle all nodes at same level

Editing

• F2: Edit selected node
• Enter: Save edit or add sibling
• Shift+Enter: Add new line (edit mode) or add sibling above
• Tab: Add child node
• Delete/Backspace: Delete node

View

• Scroll: Zoom in/out
• Drag: Pan the mindmap
• Shift+Arrow keys: Pan viewport
• \: Open search
• Escape: Deselect node

History

• Cmd/Ctrl+Z: Undo
• Cmd/Ctrl+Shift+Z: Redo

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/mindmapsmd.git
cd mindmapsmd

# Install dependencies
npm install
cd src/client && npm install && cd ../..

# Run in development mode
npm run dev

Build

npm run build

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please visit GitHub Issues.

Publishing to npm

Update version (choose one)

npm version patch # 1.0.0 -> 1.0.1 npm version minor # 1.0.0 -> 1.1.0 npm version major # 1.0.0 -> 2.0.0

Build with the new executable permission

npm run build

Create and publish the package

npm pack npm publish mindmapsmd-*.tgz