mermaid_core

mermaid_core parses Mermaid source, lays it out, and produces a backend-independent render scene. It includes an SVG renderer and a command-line tool and has no Flutter dependency.

See the live comparison demo for side-by-side output from this implementation and mermaid.js.

The package currently supports 28 diagram types, Mermaid theme directives, look: handDrawn, icons, math in labels, and alternate ELK and tidy-tree layouts. Compatibility notes and known differences from mermaid.js are kept in the repository's parity directory.

Library use

import 'package:mermaid_core/mermaid_core.dart';

void main() {
  const mermaid = Mermaid(measurer: ApproximateTextMeasurer());
  final scene = mermaid.render('''
graph TD
  A[Start] --> B{Works?}
  B -->|yes| C[Ship it]
  B -->|no| A
''');

  print(renderSceneToSvg(scene));
}

Mermaid.render returns a RenderScene containing shapes and text in absolute coordinates. renderSceneToSvg serializes that scene to SVG.

ApproximateTextMeasurer uses bundled metrics suitable for SVG output and tests. Flutter applications should use the TextPainter-based measurer from mermaid_flutter when their layout must match Flutter font rendering.

Flowchart geometry determinism

Repeated rendering of the same flowchart layout identity produces identical scene size, node bounds, path commands, and text bounds. This contract applies to Dagre and ELK layouts and to the hand-drawn look when its seed is fixed.

The layout identity includes the parsed topology and declaration order, node and edge labels, text measurer and font metrics, selected engine and its options, direction and spacing configuration, and theme values that affect text measurement or shape size. Edge interpolation is also geometry input. A change outside that identity, such as a fill or stroke color applied to existing nodes and links, does not change geometry. Class or style statements are not automatically paint-only: they can reference new node ids, and theme font changes affect measurement.

The guarantee is about resolved geometry, not byte-identical RenderScene, SVG, or PNG output. Paint data, serialization details, raster backends, and platform font availability can differ while geometry remains unchanged.

For live flowchart highlighting, apply resolved paint updates to an existing scene without parsing or laying it out again:

final highlighted = applyFlowchartPaintOverrides(
  scene,
  nodes: const {
    'current_step': FlowNodePaintOverride(
      fill: Color(0xffffcc00),
      stroke: Color(0xffcc3300),
      textColor: Color(0xff112233),
    ),
  },
  links: const {
    3: FlowLinkPaintOverride(stroke: Color(0xff0066ff), strokeWidth: 4),
  },
);

Node ids and link indices that are not present in the scene are ignored. Text, topology, spacing, interpolation, and font-metric changes still require a full render.

Command-line tool

Activate the package globally:

$ dart pub global activate mermaid_core
$ mermaid_dart diagram.mmd -o diagram.svg
$ cat diagram.mmd | mermaid_dart --theme dark

The output format is inferred from the file extension. PNG output requires rsvg-convert, resvg, or ImageMagick on PATH.

License

MIT. This package contains code derived from mermaid.js (MIT) and a vendored derivative of dart_dagre (Apache-2.0). See LICENSE and the license under lib/src/vendor/dagre.