markdraw #

An Excalidraw-inspired drawing widget for Flutter with a human-readable markdown serialization format.

Cross-platform: iOS, Android, Web, macOS, Windows, Linux.

Features #

• Hand-drawn aesthetic powered by rough_flutter
• Full element set: rectangles, ellipses, diamonds, lines, arrows, freedraw, text, images, frames
• Arrow binding with elbow routing
• Element grouping, locking, and frames with clip regions
• Selection, multi-select, resize, rotate, and nudge
• Undo/redo with drag coalescing
• Copy/paste via system clipboard
• Export to PNG and SVG (with embedded .markdraw for round-trip)
• Excalidraw JSON import/export (.excalidraw and .excalidrawlib)
• Reusable element libraries (.markdrawlib)
• Google Fonts integration with bundled Excalifont
• Responsive layout: desktop toolbar + side panels, compact bottom bar + sheets
• Keyboard shortcuts for every tool
• Pinch-to-zoom and scroll-wheel zoom
• Dark mode theming
• Live markdown split-pane editor with bidirectional sync
• Human-readable .markdraw file format (git-friendly, diffable)

Quick Start #

A minimal drawing canvas in six lines:

import 'package:flutter/material.dart' hide Element, SelectionOverlay;
import 'package:markdraw/markdraw.dart' hide TextAlign;

void main() {
  runApp(MarkdrawApp(
    home: (context, themeMode, onThemeModeChanged) => MarkdrawEditor(
      currentThemeMode: themeMode,
      onThemeModeChanged: onThemeModeChanged,
    ),
  ));
}

This gives you a full editor with toolbar, property panel, zoom controls, keyboard shortcuts, and undo/redo — no file I/O wiring needed.

Full Example with File I/O #

The example app adds file open/save, PNG/SVG export, image import, and library management via MarkdrawFileHandler:

import 'package:flutter/material.dart' hide Element, SelectionOverlay;
import 'package:markdraw/markdraw.dart' hide TextAlign;

void main() {
  runApp(MarkdrawApp(
    home: (context, themeMode, onThemeModeChanged) => _CanvasPage(
      themeMode: themeMode,
      onThemeModeChanged: onThemeModeChanged,
    ),
  ));
}

class _CanvasPage extends StatefulWidget {
  const _CanvasPage({
    required this.themeMode,
    required this.onThemeModeChanged,
  });

  final ThemeMode themeMode;
  final void Function(ThemeMode) onThemeModeChanged;

  @override
  State<_CanvasPage> createState() => _CanvasPageState();
}

class _CanvasPageState extends State<_CanvasPage> {
  final _controller = MarkdrawController();
  late final _files = MarkdrawFileHandler(controller: _controller);

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MarkdrawEditor(
      controller: _controller,
      onSave: _files.save,
      onSaveAs: _files.saveAs,
      onOpen: _files.open,
      onExportPng: _files.exportPng,
      onExportSvg: _files.exportSvg,
      onImportImage: () => _files.importImage(context),
      onImportLibrary: _files.importLibrary,
      onExportLibrary: _files.exportLibrary,
      onThemeModeChanged: widget.onThemeModeChanged,
      currentThemeMode: widget.themeMode,
    );
  }
}

API Overview #

MarkdrawEditor #

The main widget. All callbacks are optional — omit any you don't need.

MarkdrawController #

Manages editor state, tools, history, and serialization. Create one to control the editor programmatically:

final controller = MarkdrawController();

// Switch tools
controller.switchTool(ToolType.rectangle);

// Undo/redo
controller.undo();
controller.redo();

// Zoom
controller.zoomIn(canvasSize);
controller.zoomToFit(canvasSize);
controller.resetZoom();

// Serialize
final markdraw = controller.serializeScene();
final json = controller.serializeScene(format: DocumentFormat.excalidraw);

// Load
controller.loadFromContent(content, 'drawing.markdraw');

// Export
final pngBytes = await controller.exportPng();
final svgString = controller.exportSvg();

// Listen for changes
controller.addListener(() { /* rebuild */ });

MarkdrawEditorConfig #

Immutable configuration passed to the editor or controller:

MarkdrawEditorConfig(
  tools: [ToolType.select, ToolType.rectangle, ToolType.text],
  initialBackground: '#f5f5f5',
  showToolbar: true,
  showPropertyPanel: true,
  showZoomControls: true,
  showHelpButton: true,
  showLibraryPanel: true,
  showMarkdownButton: true,
  showMenu: true,
  compactBreakpoint: 600.0,
  minZoom: 0.1,
  maxZoom: 30.0,
)

MarkdrawFileHandler #

Wires file_picker and platform I/O to a controller. Provides save, saveAs, open, exportPng, exportSvg, importImage, importLibrary, and exportLibrary methods.

MarkdrawApp #

A lightweight MaterialApp wrapper that manages ThemeMode state and passes it to your builder:

MarkdrawApp(
  title: 'My Drawing App',
  initialThemeMode: ThemeMode.system,
  colorSchemeSeed: Colors.blue,
  home: (context, themeMode, onThemeModeChanged) => YourWidget(...),
)

The .markdraw Format #

Drawings are saved as markdown files with embedded sketch blocks — human-readable, git-friendly, and diffable:

---
markdraw: 1
background: "#ffffff"
grid: 20
---

# Architecture Overview

Here's how the services connect:

```sketch
rect "Auth Service" id=auth at 100,200 size 160x80 fill=#e3f2fd rounded
rect "API Gateway" id=gateway at 350,200 size 160x80 fill=#fff3e0 rounded
arrow from auth to gateway label="JWT tokens" stroke=dashed
ellipse "Database" id=db at 225,400 size 120x80 fill=#e8f5e9
arrow from gateway to db label="queries"
```

The auth service handles OAuth2 flows.

• Prose sections are preserved untouched (only sketch blocks are parsed)
• Elements map 1:1 to Excalidraw types
• IDs enable arrow binding and bound text
• Colors, stroke style, fill style, opacity, font, and lock state are inline properties

Excalidraw Interop #

Import and export .excalidraw JSON files:

// Import
controller.loadFromContent(jsonString, 'drawing.excalidraw');

// Export
final json = controller.serializeScene(format: DocumentFormat.excalidraw);

Library files (.excalidrawlib) are also supported:

controller.importLibraryFromContent(content, 'shapes.excalidrawlib');
final libJson = controller.exportLibraryContent(
  format: DocumentFormat.excalidrawLibrary,
);

Theming #

MarkdrawApp manages ThemeMode state internally. Wire it to MarkdrawEditor via the builder:

MarkdrawApp(
  home: (context, themeMode, onThemeModeChanged) => MarkdrawEditor(
    currentThemeMode: themeMode,
    onThemeModeChanged: onThemeModeChanged,
  ),
)

If you manage your own MaterialApp, pass ThemeMode and a toggle callback directly to MarkdrawEditor.

Platform Notes #

The ios/, android/, macos/, windows/, and linux/ directories are gitignored. After cloning, run flutter create . to regenerate them, then apply these manual changes:

• iOS: Add <key>UISupportsDocumentBrowser</key><true/> to ios/Runner/Info.plist — required for file picker save dialogs to work correctly.

Keyboard Shortcuts #

Development #

# Run all tests
flutter test

# Run tests and check output
flutter test 2>&1 > /tmp/test.txt

# Static analysis
flutter analyze

# Generate coverage report
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

Roadmap #

See ROADMAP.md for the full development plan.

License #

MIT — see LICENSE.