Mermaiden

Let the machine draw. Keep the meaning.

Software can generate a diagram in an instant. The harder problem is knowing whether that diagram still means what you intended after an agent, tool, or application changes it.

Mermaiden turns diagrams into typed, discoverable state. It validates semantic commands, can apply related changes atomically, preserves versioned snapshots, and renders deterministic Mermaid source—so automation can move quickly without turning meaning into guesswork.

The package produces Mermaid text rather than owning its presentation. Render that text in a Markdown viewer, a browser, or your own Mermaid CLI workflow.

Documentation

• Documentation entrance
• Tutorials
• How-to guides
• Explanation
• Architecture and ownership
• Glossary
• Technical reference

Installation

Python 3.12 or later is required.

pip install mermaiden

Source generation needs no browser or Mermaid executable. Application.validate_render() additionally requires the compatible mmdc executable and a browser.

Discover a diagram contract

from mermaiden import Application

with Application.create() as application:
    diagrams = application.available_diagrams()
    sequence = application.diagram_info("sequenceDiagram")
    description = application.diagram_description(sequence.id)
    payload_contract = application.command_payload(sequence.id, "add_participant")
    payload = payload_contract.validate({"id": "api", "label": "API", "kind": "control"})

    assert sequence in diagrams
    assert "add_participant" in description.commands
    assert payload.values["kind"] == "control"

Application.available_diagrams() returns the runtime catalog. diagram_description() and command_payload() expose the same strict contracts used by command execution, so an adapter does not need a parallel operation manifest.

Create, persist, and render

from mermaiden import Application

with Application.create() as application:
    diagram = application.create_diagram("sequenceDiagram")
    change = application.apply_batch(
        diagram,
        (
            {"operation": "add_participant", "arguments": {"id": "client", "label": "Client"}},
            {"operation": "add_participant", "arguments": {"id": "api", "label": "API"}},
            {
                "operation": "add_message",
                "arguments": {
                    "id": "request",
                    "source_id": "client",
                    "target_id": "api",
                    "label": "Request",
                },
            },
        ),
    )
    assert change.can_commit

    payload = application.snapshot(diagram).to_dict()
    restored = application.restore(payload)
    source = application.render(restored)

Snapshots use a closed, versioned envelope with registry-owned identities rather than Python import paths. Drafts may be persisted and restored, but rendering requires every blocking constraint to be resolved. See Persist and restore diagrams for the exact boundary.

To validate the generated source as SVG, first follow the consumer setup in Render and validate Mermaid.

Update, move, and reorder

from mermaiden import Application

with Application.create() as application:
    diagram = application.create_diagram("block")
    application.execute(diagram, "add_group", {"id": "source", "label": "Source"})
    application.execute(diagram, "add_group", {"id": "target", "label": "Target"})
    application.execute(
        diagram,
        "add_block",
        {"id": "catalog", "label": "Catalog", "parent_id": "source"},
    )
    application.execute(
        diagram,
        "update_element",
        {"id": "catalog", "kind": "block_node", "changes": {"label": "Product Catalog"}},
    )
    application.execute(
        diagram,
        "move_element",
        {"id": "catalog", "kind": "block_node", "parent_id": "target", "position": 0},
    )
    snapshot = application.snapshot(diagram).to_dict()
    restored = application.restore(snapshot)
    assert application.render(restored) == application.render(diagram)

The generated mutation contract records update, move, reorder, and retarget semantics and per-diagram coverage. Use Mutate diagrams for task-focused mutation, removal, and atomic-rejection guidance.

Development

Create the development environment and run the fast tier:

uv sync --locked --group dev
make fast-check

The contribution guide covers repository verification and generated contracts. Documentation is built strictly with make documentation-check; external links are checked with make documentation-linkcheck.

License

Mermaiden is proprietary software. No permission to use, copy, modify, or distribute it is granted without prior express written permission. See LICENSE for the complete terms.