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.

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

# 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

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.
• 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.
• Unthemed output stays available. If no explicit theme or Mermaid hint is present, SVG rendering keeps the existing unthemed 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.

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
• 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
• mmds for MMDS parsing, replay, and Mermaid generation

The rest of the crate tree (diagrams, engines, graph, render, mermaid, and timeline) 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

Verify the examples compile with cargo test --examples.

License

MIT