mmdflux

Render Mermaid diagrams as terminal text, SVG, and structured JSON.

mmdflux is a diagram rendering toolkit built in Rust. It ships as a CLI, a Rust library, and a WebAssembly package — all from the same codebase. It includes its own graph layout engine with native orthogonal routing, a character-grid renderer for terminal output, and MMDS — a structured JSON format designed for tooling, adapters, and LLM/agent pipelines.

Playground · Releases · Gallery · MMDS Spec

At a glance

One Mermaid source, multiple outputs: terminal text, SVG, and machine-readable JSON.

Mermaid source (docs/assets/readme/at-a-glance.mmd)

graph TD
    subgraph sg1[Horizontal Section]
        direction LR
        A[Step 1] --> B[Step 2] --> C[Step 3]
    end
    Start --> A
    C --> End

SVG output (mmdflux --format svg --layout-engine flux-layered --curve linear-rounded ...)

Text output (mmdflux --format text ...)

               ┌───────┐
               │ Start │
               └───────┘
                   │
      ┌────────────┘
      │
      │
┌─────┼── Horizontal Section ────────┐
│     ▼                              │
│ ┌────────┐  ┌────────┐  ┌────────┐ │
│ │ Step 1 │─►│ Step 2 │─►│ Step 3 │ │
│ └────────┘  └────────┘  └────────┘ │
│                             │      │
└─────────────────────────────┼──────┘
                              │
                   ┌──────────┘
                   │
                   ▼
                ┌─────┐
                │ End │
                └─────┘

MMDS JSON output: docs/assets/readme/at-a-glance.mmds.json

Why mmdflux

No runtime dependencies. A single compiled binary. No Node.js, no headless browser, no Puppeteer.

Terminal text is a first-class output. Text rendering isn't a secondary mode — it has its own grid layout system, orthogonal edge routing, and Unicode box-drawing characters designed to be readable in a terminal.

Native orthogonal routing. The flux-layered engine treats layout and routing as one solve contract. Edges follow right-angle paths with deterministic fan-in/fan-out policies and shape-aware attachment points — addressing one of the most common complaints about Mermaid's rendering.

Structured JSON for tooling and agents. MMDS (Machine-Mediated Diagram Specification) outputs positioned graph data — node coordinates, routed edge paths, subgraph bounds — so downstream tools can consume diagram geometry without parsing SVG or scraping pixels.

Materialized diagram views. Rust adapters can filter canonical MMDS payloads into read-side views for focused rendering, traversal, or event correlation without inventing a separate graph query language.

Compound graph layout. Subgraphs are laid out as part of a single compound graph, not rendered recursively. This produces globally optimized positioning and consistent cross-boundary edge routing.

Multiple engines for graph-family diagrams. The default flux-layered engine handles flowchart/class/state text, SVG, and MMDS output. Switch to mermaid-layered for Mermaid-compatible graph output.

Ecosystem

Install

Homebrew (recommended)

brew tap kevinswiber/mmdflux
brew install mmdflux

Cargo

cargo install mmdflux

Prebuilt binaries

Download platform binaries from GitHub Releases.

Quick Start

# Render a Mermaid file to text (default format)
mmdflux diagram.mmd

# Read Mermaid from stdin
printf 'graph LR\nA-->B\n' | mmdflux

# Disable ANSI color for text/ascii output
NO_COLOR=1 mmdflux --format text diagram.mmd

# Override NO_COLOR for a single invocation
NO_COLOR=1 mmdflux --format text --color always diagram.mmd

# SVG output
mmdflux --format svg diagram.mmd -o diagram.svg

# SVG output with a named theme
mmdflux --format svg --svg-theme dark diagram.mmd -o diagram.svg

# SVG output with terminal-aware light/dark theme selection
mmdflux --format svg --svg-theme-auto diagram.mmd -o diagram.svg

# Browser-oriented SVG with CSS variables plus hex fallbacks
mmdflux --format svg --svg-theme dark --svg-theme-mode dynamic diagram.mmd -o diagram.svg

# MMDS JSON output with routed geometry detail
mmdflux --format mmds --geometry-level routed diagram.mmd

# Lint mode (validate input and print diagnostics)
mmdflux --lint diagram.mmd

With ANSI enabled, text/ascii output maps Mermaid styling to terminal colors where it has a clear analogue: node style/classDef fill, stroke, and color drive node background, border, and label color; flowchart linkStyle ... stroke:<color> drives edge and arrow foreground color; SVG-specific properties such as stroke-width and stroke-dasharray remain no-ops in text/ascii output.

See more examples in the sections below.

What It Supports

• Diagram types: flowchart, class, sequence, state
• Output formats: Unicode text, ASCII text, SVG, MMDS JSON
• Layout directions: TD, BT, LR, RL (with per-subgraph overrides)
• Edge styles: solid, dotted, thick, invisible, cross-arrow, circle-arrow
• Routing: orthogonal, polyline, direct (with curve options: basis, linear, linear-rounded, linear-sharp)
• Round-trip conversion: Mermaid to MMDS and MMDS back to Mermaid

Graph-Family Engines

Sequence diagrams use a separate timeline renderer, support text/ascii, SVG, and MMDS output, and do not accept --layout-engine.

SVG edge presets

# Smooth orthogonal corners (default)
mmdflux --format svg diagram.mmd -o diagram.svg

# Curved orthogonal basis paths
mmdflux --format svg --edge-preset curved-step diagram.mmd -o diagram.svg

# Explicit curve control
mmdflux --format svg --curve linear-rounded diagram.mmd -o diagram.svg

SVG Theming

SVG theming is opt-in and affects SVG output only.

• Explicit config wins. CLI flags and RenderConfig.svg_theme take precedence over Mermaid source hints.
• Auto-theme is explicit. --svg-theme-auto resolves to a concrete named theme before render, so Mermaid source hints stay suppressed when auto-theme is enabled.
• Mermaid hints are supported. config.theme in YAML frontmatter and %%{init: {"theme": "..."}}%% both select a named SVG theme when no explicit SVG theme is supplied.
• Un-themed output stays available. If no explicit theme or Mermaid hint is present, SVG rendering keeps the existing un-themed palette.
• Static mode is the default. Static mode emits concrete hex colors for maximum rasterizer compatibility.
• Dynamic mode is additive. --svg-theme-mode dynamic emits the same hex fallbacks plus root CSS variables and a <style> block for browser embedding.
• Default auto-theme mapping is light:default,dark:dark. Override it with --svg-theme-auto=light:zinc-light,dark:dracula when a different light/dark pair is a better fit.

Built-in themes

The beautiful-mermaid themes are adapted from beautiful-mermaid by lukilabs. Mermaid-family themes (default, dark, forest, neutral) are also resolved from %%{init: {"theme": "..."}}%% directives and YAML frontmatter when no explicit --svg-theme is provided.

Supported theme slots for per-slot overrides: bg, fg, line, accent, muted, surface, and border.

use mmdflux::{OutputFormat, RenderConfig, SvgThemeConfig, SvgThemeMode, render_diagram};

let svg = render_diagram(
    "graph TD\nA-->B\n",
    OutputFormat::Svg,
    &RenderConfig {
        svg_theme: Some(SvgThemeConfig {
            name: Some("dark".into()),
            mode: SvgThemeMode::Dynamic,
            ..Default::default()
        }),
        ..Default::default()
    },
)?;

SVG <defs> blocks are also pruned to the markers each diagram actually uses, so simple flowcharts and sequence diagrams no longer carry unused arrowhead definitions.

Documentation

• Developer setup — prerequisites and first-time setup
• Gallery — rendered output for 152 fixtures
• MMDS specification — structured JSON format
• Edge routing design — routing internals

Rust API Surface

Most Rust integrations should stay on the high-level runtime facade:

• render_diagram
• materialize_diagram
• render_document
• detect_diagram
• validate_diagram

Pair those entrypoints with RenderConfig and OutputFormat unless you are building an adapter or tooling layer that needs explicit preparation control.

The low-level API is smaller and adapter-focused:

• mmdflux::builtins::default_registry() for the builtin diagram registry
• registry and payload for explicit detect/parse/payload flows
• graph and timeline for family-specific IR inspection
• mmds for MMDS Document parsing, replay, and Mermaid generation
• views for materializing filtered read-side MMDS payloads

The rest of the crate tree (diagrams, engines, render, and mermaid) consists of internal implementation modules and is not part of the supported public contract.

Examples

• examples/high_level_render.rs — top-level render_diagram workflow
• examples/registry_adapter.rs — explicit registry-driven detection and preparation
• examples/mmds_replay.rs — MMDS profile negotiation, replay, and Mermaid regeneration
• examples/materialized_view.rs — materialize a focused MMDS view and replay it as text
• examples/commands_events_views.rs — apply MMDS commands, inspect model events, project a view, and render it
• examples/snapshot_diff.rs — compare two materialized MMDS documents with the snapshot diff API

Verify the examples compile with cargo test --examples.

License

MIT