Skip to main content Skip to navigation
Back to Projects

puml

PlantUML-compatible diagrams without Java or Graphviz: a Rust compiler with its own layout engine, emitting SVG/PNG/PDF from a CLI, LSP and in-browser WASM.

RustWebAssemblywinnowresvgsvg2pdfLSPZolaCodeMirror
The puml studio editor with PlantUML class source on the left and the SVG class diagram, rendered by the in-browser WASM engine, on the right.

UML that compiles: PlantUML diagrams, no Java, no Graphviz.

PlantUML is the most expressive text-to-diagram language around, but rendering it takes a JVM and usually Graphviz. That's heavy in CI, awkward in an editor, and impossible in a browser tab. puml is a Rust compiler for the same language that brings its own layout engine, so one binary, or one WebAssembly module, turns .puml text into SVG, PNG, JPEG, WebP or PDF.

The quickest way to see it is the live editor: type on the left and the diagram re-renders on the right, entirely in your browser.

How it works

Source goes through a frontend (PlantUML, puml's own lighter PicoUML dialect, or an early Mermaid adapter), a preprocessor that handles !include, !define, conditionals, macros and themes, a parser built on winnow, and a normalizer that turns the syntax tree into a model for each diagram family. Then comes layout, and output as deterministic SVG that resvg rasterizes or svg2pdf converts. Here is puml drawing its own architecture:

The part that replaces Graphviz is a Sugiyama-style hierarchical layout. It assigns ranks by longest path, reduces edge crossings with barycenter sweeps, then runs a transposition pass that counts actual crossings between adjacent layers and keeps a swap only if the count strictly drops. Edges are routed orthogonally through deterministic channels, and there's a separate spline router for curved edges, whose module doc explains at some length why rounding off the corners of an orthogonal path is not the same thing as a real spline. Sequence diagrams, class diagrams, mind maps, Gantt charts and several others have their own layouts.

Output is deterministic by construction. Layout uses ordered maps throughout, and text is measured with font-free arithmetic, so a render never depends on the fonts installed on the machine. Before any SVG is written, the render is a typed scene that invariant tests check for text collisions, bounds and arrowhead geometry.

Everywhere the text is

One language service backs three surfaces. The puml CLI has --check, --watch and --dump ast|model|scene to inspect every stage. puml-lsp is a full language server with completion, hover, rename, formatting and diagnostics. And the WASM build runs the live editor on the docs site, diagnostics included.

Breadth, honestly

The syntax tree knows 28 diagram kinds, from sequence and class diagrams to Gantt charts, JSON and YAML trees, Salt wireframes, regex railroads and network diagrams. Depth varies a lot between them. The project's own parity map marks some families as stubs and only a handful as broad, and the README calls it "PlantUML-compatible — not a claim of complete 1:1 parity". There's no conformance percentage, because none has been measured. What exists instead is a public feature manifest of what's supported, partial or risky, and a differential harness that renders the same fixtures through puml and the real PlantUML JAR and compares element counts, text and colours.

How it was built

puml was an experiment in fast, AI-assisted engineering, which the README says openly: 1,383 commits and about 800 merged pull requests between May 14 and June 5, 2026. The guardrails are what held it together: deterministic output, snapshot and invariant tests, visual baselines, a binary-size gate, and scripts that stop files and modules from growing into monoliths.

Status

It's an early 0.x release, MIT licensed, and mostly paused since June 2026, apart from a hardening pass in early October. The docs site, gallery and editor are live. v0.2.6 is out with release binaries (Linux and macOS, with cosign signatures and checksums), a Homebrew formula and a crates.io package. The crates.io release goes out through trusted publishing, so no long-lived registry token is stored in the repo. A VS Code extension, alliecatowo.puml-vscode (0.2.6), is on Open VSX and needs the puml binary on your PATH; it isn't on the VS Code Marketplace.

The October pass was mostly security and correctness. file:// includes are now confined to an include root (the CLI, the VS Code fallback and the MCP server all pass one), and there are tests for the MCP server's include and output-path limits. Fixes include XML-invalid character references, nested fences, every @start* block type, LSP positions in UTF-16 units, --watch using the normal pipeline, !ifdef on variables, and a 64-megapixel cap on raster output. The release workflow was also tightened: pinned actions, per-job permissions and a check that the tag matches Cargo.toml. v0.2.5 exists on GitHub only, because its crates.io publish failed on a trusted-publishing setting; v0.2.6 is the first version where every channel went out cleanly. Diagnostic columns are still counted in characters rather than UTF-16 units, and several lower-priority bugs are open.

brew install alliecatowo/tap/puml
# or the release binary
curl -fsSL https://raw.githubusercontent.com/alliecatowo/puml/main/scripts/install.sh | sh
# or from crates.io
cargo install puml
puml hello.puml