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);

Supported diagram types

“Import-only” means the diagram imports onto the canvas, but exporting reproduces it as a flowchart (PinePaper has no sequence/class/ER exporter), so it does not survive an export→import cycle as the same type.

Round-trip fidelity (flowchart & state diagrams)

A PinePaper export re-imports with layout, colors, and clusters intact:

• Positions are preserved. Export writes %% pinepaper:pos <id> <x> <y> comments; import reads them and skips auto-layout when every node has one. These are Mermaid comments, so the exported file still renders in any Mermaid tool — they’re simply ignored there.
• Styling round-trips. style, classDef, and class are applied on import; export emits a style <id> fill:…,stroke:…,stroke-width:…px line for any node whose colors differ from the shape default.
• Subgraphs become labeled container boxes on the canvas, and export re-emits them as subgraph <title> … end blocks.

Limitations

• click directives are intentionally skipped (never imported or exported) — PinePaper does not attach JavaScript callbacks from imported diagram text.
• Note blocks in state diagrams are parsed but not rendered on the canvas.
• Subgraph layout: the container box encloses members at their auto-laid-out positions; auto-layout doesn’t yet cluster a subgraph’s members together, so a box may be larger than a hand-drawn cluster until you reposition.
• Sequence / class / ER are import-only (see the table above).