Mermaid Import/Export

Import Mermaid flowchart and state diagram text to create PinePaper diagrams, or export existing diagrams as valid Mermaid syntax. Uses a custom zero-dependency parser — no external libraries required.

Quick Start

// Import a Mermaid flowchart
const result = app.importMermaid(`flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C([Done])
  B -->|No| D[(Database)]
  D --> A`);

// Export current diagram as Mermaid text
const mermaidText = app.exportMermaid();

importMermaid(mermaidText, options)

Import Mermaid text and create diagram shapes and connectors on the canvas.

Parameters:

• mermaidText (string, required) — Mermaid flowchart or state diagram text. The format is auto-detected.
• options (Object, optional):
  • autoLayout (boolean, default: true) — Apply hierarchical layout after import, using the parsed direction (TD, LR, etc.)
  • clearExisting (boolean, default: false) — Clear all existing diagram shapes and connectors before importing

Returns:

{
  success: boolean,       // true if at least one node was created
  nodes: Array<{
    id: string,           // Mermaid node ID (e.g., "A")
    item: paper.Item,     // Created Paper.js shape group
    label: string,        // Text label
    shapeType: string     // PinePaper shape type
  }>,
  edges: Array<{
    from: string,         // Source node ID
    to: string,           // Target node ID
    connector: paper.Item // Created connector group
  }>,
  errors: string[]        // Non-fatal parsing warnings
}

Examples:

// Basic import with auto-layout
const result = app.importMermaid(`flowchart LR
  A[Input] --> B[Process] --> C[Output]`);

console.log(result.nodes.length); // 3
console.log(result.edges.length); // 2

// Replace existing diagram
app.importMermaid(newDiagramText, {
  clearExisting: true,
  autoLayout: true
});

// Import without layout (position manually)
app.importMermaid(text, { autoLayout: false });

exportMermaid(options)

Export the current diagram as Mermaid text.

Parameters:

• options (Object, optional):
  • format (string, default: 'flowchart') — 'flowchart' or 'stateDiagram'
  • direction (string, default: 'TD') — Flow direction: 'TD', 'LR', 'BT', 'RL'

Returns: string — Valid Mermaid text.

Examples:

// Export as flowchart (default)
const text = app.exportMermaid();
// flowchart TD
//   A["Start"]
//   B{"Decision"}
//   A --> B

// Export left-to-right
const lr = app.exportMermaid({ direction: 'LR' });

// Export as state diagram
const stateDiagram = app.exportMermaid({ format: 'stateDiagram' });

Supported Syntax

Shape Mapping

Edge Styles

Edge Labels

A -->|Yes| B          %% Pipe syntax
A --Yes--> B          %% Inline syntax
A ==Yes==> B          %% Thick with label
A -.Text.-> B         %% Dashed with label

Chained Edges

A --> B --> C --> D    %% Creates 3 edges

Subgraphs

subgraph title
  A --> B
end

Comments

%% This is a comment
A --> B  %% Inline comment

State Diagrams

State diagrams are auto-detected from the stateDiagram-v2 header.

app.importMermaid(`stateDiagram-v2
  [*] --> Idle
  Idle --> Processing : Start
  state check <<choice>>
  Processing --> check
  check --> Done : Valid
  check --> Error : Invalid
  Error --> Idle : Retry
  Done --> [*]`);

State Diagram Syntax

Export as State Diagram

const text = app.exportMermaid({ format: 'stateDiagram', direction: 'LR' });
// stateDiagram-v2
//   direction LR
//   [*] --> Idle
//   Idle --> Active : Start

Direct Bridge Access

For advanced parsing without creating canvas items:

const bridge = app.diagramSystem.mermaidBridge;

// Parse without importing
const parsed = bridge.parse(mermaidText);
// {
//   type: 'flowchart' | 'stateDiagram',
//   direction: 'TD' | 'LR' | ...,
//   nodes: Map<id, { id, label, shapeType }>,
//   edges: [{ from, to, label, edgeType }],
//   subgraphs: [{ id, label, nodeIds }],
//   errors: string[]
// }

Round-Trip Example

// 1. Import a diagram
app.importMermaid(`flowchart TD
  A[Start] --> B{Validate}
  B -->|OK| C([Done])
  B -->|Fail| D[Retry]
  D --> A`);

// 2. Modify shapes on the canvas
// (drag, restyle, add new shapes...)

// 3. Export back to Mermaid
const updated = app.exportMermaid({ direction: 'LR' });
console.log(updated);

Limitations

• Supported types: Flowcharts and state diagrams only. Sequence, class, ER, pie, and gantt diagrams are not supported.
• Styling directives (style, classDef, class, click) are silently skipped.
• Note blocks in state diagrams are parsed but not imported.
• Subgraphs are parsed but not created as visual groups on the canvas.
• Position data is not preserved across round-trips — export re-imports require auto-layout.