Crate mmdflux

Expand description

mmdflux — Mermaid diagrams to text, SVG, and MMDS

mmdflux parses Mermaid diagram syntax and renders it as Unicode/ASCII text, SVG, or structured JSON (MMDS). Supported diagram types: flowchart, class, and sequence.

§High-Level API

Most consumers only need three functions and two config types:

render_diagram — detect, parse, and render in one call
detect_diagram — detect the diagram type without rendering
validate_diagram — parse and return structured JSON diagnostics
OutputFormat — Text, Ascii, Svg, or Mmds
RenderConfig — layout engine, routing, padding, color, and more

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

let input = "graph TD\n    A[Collect] --> B[Render]";

// Render as Unicode text
let text = render_diagram(input, OutputFormat::Text, &RenderConfig::default()).unwrap();
println!("{text}");

// Render as SVG
let svg = render_diagram(input, OutputFormat::Svg, &RenderConfig::default()).unwrap();
assert!(svg.contains("<svg"));

// Render as MMDS JSON (structured interchange format)
let json = render_diagram(input, OutputFormat::Mmds, &RenderConfig::default()).unwrap();
assert!(json.contains("\"diagram_type\""));

§Customizing output

Use RenderConfig to control layout direction, engine selection, edge routing, padding, color mode, and more:

use mmdflux::{OutputFormat, RenderConfig, render_diagram};
use mmdflux::LayoutConfig;
use mmdflux::format::RoutingStyle;

let config = RenderConfig {
    routing_style: Some(RoutingStyle::Direct),
    padding: Some(2),
    layout: LayoutConfig {
        rank_sep: 30.0,
        ..LayoutConfig::default()
    },
    ..RenderConfig::default()
};

let output = render_diagram("graph LR\n    A-->B-->C", OutputFormat::Text, &config).unwrap();
println!("{output}");

§Validation

validate_diagram returns structured JSON diagnostics suitable for editor integrations and CI pipelines:

use mmdflux::validate_diagram;

let result = validate_diagram("graph TD\n    A-->B");
let json: serde_json::Value = serde_json::from_str(&result).unwrap();
assert_eq!(json["valid"], true);

§Low-Level API

For adapters, tooling, or workflows that need explicit control over the detect → parse → payload → render pipeline, the low-level API provides:

builtins::default_registry — the built-in diagram registry
registry — DiagramRegistry, DiagramInstance, and ParsedDiagram traits
payload — the payload::Diagram enum returned by ParsedDiagram::into_payload
graph — graph-family IR types (Graph, Node, Edge, Shape, Direction)
timeline — timeline-family types (Sequence)
mmds — MMDS parsing, hydration to graph::Graph, profile negotiation, and Mermaid regeneration

use mmdflux::builtins::default_registry;
use mmdflux::payload::Diagram;

let input = "graph TD\n    A[Draft] --> B[Published]";
let registry = default_registry();

// Detect diagram type
let resolved = registry.resolve(input).expect("should detect diagram type");
println!("detected: {} ({:?})", resolved.diagram_id(), resolved.family());

// Parse and build payload
let instance = registry.create(resolved.diagram_id()).unwrap();
let payload = instance
    .parse(input).unwrap()
    .into_payload().unwrap();

// Inspect the payload
match payload {
    Diagram::Flowchart(graph) => {
        println!("flowchart with {} nodes", graph.nodes.len());
    }
    Diagram::Class(graph) => {
        println!("class diagram with {} nodes", graph.nodes.len());
    }
    Diagram::State(graph) => {
        println!("state diagram with {} nodes", graph.nodes.len());
    }
    Diagram::Sequence(seq) => {
        println!("sequence with {} participants", seq.participants.len());
    }
}

§MMDS interchange

MMDS is a structured JSON format for diagram geometry. Use the mmds module to parse MMDS input, hydrate it to a graph::Graph, or regenerate Mermaid source. To render MMDS input to text/SVG, pass it to render_diagram which auto-detects MMDS:

use mmdflux::mmds::{from_str, generate_mermaid_from_str};

let mmds_json = r#"{
  "version": 1,
  "profiles": ["mmds-core-v1"],
  "defaults": {
    "node": { "shape": "rectangle" },
    "edge": { "stroke": "solid", "arrow_start": "none", "arrow_end": "normal", "minlen": 1 }
  },
  "geometry_level": "layout",
  "metadata": {
    "diagram_type": "flowchart",
    "direction": "TD",
    "bounds": { "width": 100.0, "height": 80.0 }
  },
  "nodes": [
    { "id": "A", "label": "Start", "position": { "x": 50.0, "y": 20.0 },
      "size": { "width": 50.0, "height": 20.0 } },
    { "id": "B", "label": "End", "position": { "x": 50.0, "y": 60.0 },
      "size": { "width": 50.0, "height": 20.0 } }
  ],
  "edges": [{ "id": "e0", "source": "A", "target": "B" }]
}"#;

// Hydrate to graph IR
let graph = from_str(mmds_json).unwrap();
assert_eq!(graph.nodes.len(), 2);

// Regenerate Mermaid source
let mermaid = generate_mermaid_from_str(mmds_json).unwrap();
assert!(mermaid.contains("flowchart TD"));

Re-exports§

pub use errors::RenderError;
pub use format::ColorWhen;
pub use format::OutputFormat;
pub use format::TextColorMode;

Modules§

builtins: Built-in diagram registry assembly.
errors: Error and diagnostic types for rendering and validation.
format: Output format, curve, edge preset, and routing style definitions.
graph: Shared graph-family core.
mmds: MMDS interchange contract and output-generation namespace.
payload: Runtime payload contract returned by crate::registry::ParsedDiagram::into_payload.
registry: Diagram registry for type detection and dispatch.
simplification: Post-routing path simplification levels for MMDS and SVG output.
timeline: Timeline-family runtime namespaces.

Structs§

EngineAlgorithmId: Combined engine + algorithm identifier for explicit layout engine selection. Combined engine+algorithm identifier for explicit layout engine selection.
LayoutConfig: Layout configuration for the Sugiyama hierarchical engine. Canonical caller-facing graph layout configuration.
RenderConfig: Configuration for rendering.
RuntimeConfigInput: Serde-friendly config input for JSON consumers (WASM, API). Serde-friendly render config accepted from JSON callers.
SvgThemeConfig: SVG theme configuration owned by the runtime facade.

Enums§

AlgorithmId: Algorithm identifier (e.g., Layered, Mrtree) used in engine selection. Algorithm identifier used in the combined engine+algorithm taxonomy.
EngineId: Engine identifier (e.g., Flux, Mermaid, Elk). Engine family identifier used in the combined engine+algorithm taxonomy.
LabelDummyStrategy: Layout configuration for the Sugiyama hierarchical engine. Strategy for placing edge-label dummies within long edge chains.
LayoutDirection: Layout configuration for the Sugiyama hierarchical engine. Direction for the public graph-layout config.
Ranker: Layout configuration for the Sugiyama hierarchical engine. Ranking algorithm selection for the public graph-layout config.
SvgThemeMode: SVG theme rendering mode.

Functions§

apply_svg_surface_defaults: Apply default SVG surface settings (curve, engine) when format is SVG. Apply SVG surface defaults for flux-layered engine.
detect_diagram: Detect the diagram type from input text. Detect the diagram type from input text.
render_diagram: Detect, parse, and render a diagram in one call. Detect, parse, and render a diagram in one call.
validate_diagram: Validate input and return structured JSON diagnostics. Validate Mermaid input and return structured diagnostics as JSON.

Crate mmdflux

Crate mmdflux Copy item path

§High-Level API

§Customizing output

§Validation

§Low-Level API

§MMDS interchange

Re-exports§

Modules§

Structs§

Enums§

Functions§

Crate mmdflux