Merman

Merman is an independent, parity-focused Rust implementation of Mermaid.js. It targets mermaid@11.16.1 and parses, analyzes, lays out, and renders Mermaid source without starting Node.js, Puppeteer, Chromium, or another JavaScript runtime in the native render path.

Use it as a Rust library, an mmdc-style CLI, a browser WASM package, an editor language engine, or a native SDK. The same parser-owned semantics drive every surface.

Adopted by Zed. Zed replaced its previous Rust Mermaid backend with Merman after comparing real diagrams, citing Merman's rendering accuracy as the reason for the move. Read the merged integration.

See The Output

These are headless merman-cli outputs. The Playground has a searchable example for every admitted family.

Why Merman

• Parity is tested at multiple layers. Source-backed semantic JSON, typed layout snapshots, and pinned upstream SVG DOM baselines catch different classes of drift. The current primary matrix covers 35 Mermaid families.
• Rendering is browserless by design. Native applications, CI jobs, documentation builds, and editors do not need a bundled browser just to turn diagram text into SVG.
• One language model serves every workflow. Rendering, diagnostics, LSP features, the Playground, and bindings share parser-owned facts instead of maintaining parallel regex or syntax implementations.
• Outputs are explicit contracts. Mermaid-style SVG, export-safe SVG, PNG, JPEG, vector PDF, ASCII/Unicode, semantic JSON, and layout JSON remain separately selectable.

Quick Start

[!IMPORTANT] This README describes the unreleased 0.8.0-alpha.4 source contract. The Rust and CLI commands below install the current repository source; published registry packages can still be alpha.3. Pin a full commit before using an unreleased build in CI or production.

Rust

Add the alpha.4 candidate from Git:

cargo add merman --git https://github.com/Latias94/merman

Render one Mermaid source string without constructing a renderer:

use merman::render_svg;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let svg = render_svg("flowchart TD\n  A[Start] --> B[Done]")?;
    std::fs::write("diagram.svg", svg)?;
    Ok(())
}

diagram.svg is now a standalone SVG file that can be opened directly or embedded in a page.

Choose the narrowest Rust entry point that owns the task:

render_svg uses the complete deterministic SVG defaults and reports ordinary prose or empty input as RenderSvgError::NoDiagram. render_svg_with_id is the same one-shot path with a caller-owned ID; supply IDs that remain unique after merman::svg::sanitize_svg_id normalization.

The task-oriented Rust examples are self-contained files that can be copied into another crate. They cover one-shot SVG, same-DOM embedding, renderer reuse, PNG and terminal output, semantic and layout inspection, deterministic dates, site configuration, presentation themes, and consumer-specific SVG pipelines.

After alpha.4 is published, the registry equivalent will be:

cargo add merman@^0.8.0-alpha.4

Command Line

Install the current complete CLI from source and render a diagram:

cargo install --git https://github.com/Latias94/merman --locked merman-cli
printf 'flowchart LR\n  Source --> Merman --> SVG\n' | \
  merman-cli render - --output diagram.svg

diagram.svg now contains the rendered diagram; the native path starts no browser or JavaScript runtime.

Native commands use explicit single-diagram and Markdown workflows:

merman-cli render diagram.mmd
merman-cli render diagram.mmd --format png --theme dark --background transparent
merman-cli batch README.md

Scripts migrating from the official CLI use the pinned compatibility command:

merman-cli mmdc -i diagram.mmd -o diagram.svg

Root help and completions do not advertise -i / -o. Root invocations that begin with an mmdc option remain permanently supported as silent compatibility aliases and use the exact merman-cli mmdc parser and execution path; bare root inputs and native-only root options fail with guidance to an explicit workflow. New scripts should still choose render, batch, or explicit mmdc so their intended contract is visible.

Native render and batch use -f/--format; their hidden -e aliases share the v0.9.0 removal date, but mmdc -e/--outputFormat remains part of the compatibility interface. See the merman-cli guide for the migration table, PDF, ASCII/Unicode, Iconify, runtime policy, and recoverable batch output.

Browser

Install the complete browser package from the published alpha channel and initialize it once per browser realm:

npm install @mermanjs/web@alpha

import { initMerman, renderSvg } from "@mermanjs/web";

await initMerman();
const svg = renderSvg(`flowchart TD
  A[Start] --> B[Done]`);

The call returns the rendered SVG string in svg; it does not mutate the page.

The browser package does not provide a Node.js or SSR fallback. See the browser package guide for Worker lifecycle, custom WASM loading, and resource policy.

The npm alpha channel can trail this source tree. Check the installed package version before using an alpha.4-only contract.

Pin Unreleased Source

Replace FULL_COMMIT_SHA with a reviewed commit when an unreleased integration must be reproducible:

cargo install --git https://github.com/Latias94/merman --rev FULL_COMMIT_SHA --locked merman-cli
cargo add merman --git https://github.com/Latias94/merman --rev FULL_COMMIT_SHA

Choose Your Surface

For a shell, cargo binstall merman-cli installs the registry-selected release, while brew install merman-cli follows the stable Homebrew formula. Those external channels can trail the current source documentation, so check merman-cli --version before depending on a new contract.

The source installation above pins an immutable commit. Starting with 0.8.0-alpha.4, direct GitHub archives bundle checked completion and man-page assets, while the complete binary keeps merman-cli completion <shell> as the portable fallback. The CLI guide compares the installation channels and their on-disk support files.

Publication routes differ by platform. The package surface guide distinguishes registry packages from repository or CI artifacts.

Bring Only What You Need

Cargo features select observable capabilities and output backends, not diagram families. Every parser-capable build keeps the same Mermaid language catalog.

For example, a basic SVG dependency is:

[dependencies]
merman = { git = "https://github.com/Latias94/merman", default-features = false, features = ["svg"] }

A lint-only CLI can omit rendering and export dependencies:

cargo install --git https://github.com/Latias94/merman --locked merman-cli \
  --no-default-features --features analysis

If an input needs a layout engine or math renderer that was not compiled, Merman returns a typed missing-capability error instead of silently changing the diagram. The capability guide documents exact feature forwarding, browser packages, artifact profiles, and runtime/resource policy.

Compatibility, Honestly

Merman prioritizes parser, model, layout, theme, sanitizer, and SVG DOM convergence with pinned Mermaid source. It does not claim byte-for-byte Chromium pixels.

• Browser font fallback, getBBox() floats, foreignObject, and RoughJS path geometry can remain documented residuals where no robust headless derivation exists.
• Mermaid-parity SVG can contain HTML labels. Use render_resvg_compatible_svg_sync() or an export command when a raster consumer cannot render foreignObject; browser DOM insertion still requires a Web-host admission policy.
• PNG, JPEG, and PDF are integration outputs with explicit allocation and resource limits; they are not browser screenshot parity contracts.
• ASCII/Unicode support varies by diagram family and should be capability-checked.

See the current alignment dashboard, SVG pipeline guide, and benchmark methodology for the exact evidence boundary.

Documentation

• Upgrade from 0.8.0-alpha.3 to 0.8.0-alpha.4
• Choose capabilities and build profiles
• Diagram coverage and parity
• CLI reference
• Browser packages
• Integrations and editor workflows
• Host text measurement
• Rendering security
• Changelog

Development

cargo nextest run --workspace
cargo fmt --all -- --check
cargo run -p xtask -- verify --strict

The strict gate verifies generated contracts, all-family SVG evidence, package surfaces, browser tests, and release legal material against the pinned reference bundle.

License And Attribution

Merman is available under the Apache License 2.0 or MIT License.

Source translations, fixtures, embedded resources, behavioral references, and their exact revisions are recorded in THIRD_PARTY_NOTICES.md and the machine-readable component inventory.

Merman is independent of, and not affiliated with, endorsed by, or sponsored by the Mermaid project or its maintainers.