Docs
Install the tool, render locally, choose style and palette, verify edits, and hand diagrams to agents without rewriting source by hand.
Start with setup or examples; keep reading for the typed-edit guide. Op shapes and warning codes are pinned by capabilities.json.
Start here
- First run
- Use locally
- Appearance
- Debug
See one typed edit
Change the review label while keeping the same three node identities and two connections. Replay the results below, generated by the real API during the site build.
mutate(diagram, {"kind":"set_label","target":"Review","label":"Approved"})
Mermaid source
flowchart LR
accTitle: Review workflow
accDescr: Draft flows through review to publication.
Draft[Draft] --> Review[Review] --> Publish[Publish]Mermaid source
flowchart LR
accTitle: Review workflow
accDescr: Draft flows through review to publication.
Draft --> Review[Approved]
Review --> Publish
Original diagram verified: 0 warnings.
Guide: editing a diagram without regenerating it
A render-only tool makes an agent rebuild the whole diagram to move one node. Agentic Mermaid keeps the diagram structured, so an edit is five small steps, and verify gates the last one.
Most diagram tools render and stop. You hand them source, they hand back a picture, and to change one node you send the whole source again. That is fine for a person editing by hand and wasteful for an agent editing in a loop, where every regeneration risks moving nodes that were already correct.
The fix is to treat an existing diagram as structured data, not a string. A typed surface exposes source nodes, edges and other family-specific objects an agent can name and change, and refuses edits it cannot make safely. These source objects are distinct from drawing parts; see the shared vocabulary. The loop has five steps.
1 · Parse
Read the source into its family model. Inspect the parsed body and diagnostics before choosing an edit.Preserved source and structured edit support are different capabilities. A preserved body can round-trip without exposing typed operations.
2 · Narrow
Select the typed family, such as Flowchart or Sequence, before applying its operations.Narrowing identifies the available operations. An edit can recompute layout; unchanged elements are not guaranteed to keep their coordinates.
verify sits between mutate and serialize; a warning sends the work back to narrow.3 · Mutate
Apply a named operation to the typed family value. The operation returns a new typed model; it does not rewrite the source by hand.
mutate(diagram, { kind: "add_edge", from: "V", to: "R", label: "ok" })
// returns { ok: true, value: ValidDiagram } or a structured error
4 · Verify
Inspect verifyMermaid's ok, warning codes, severities and check evidence. Errors block a successful return; warnings still need judgement. Verification does not prove that an explanation is true or that every source edit is lossless. Use semantic facts for task-critical meaning and review the artifact when appearance matters. The library reference describes result shapes and recovery.
5 · Serialize
Write the typed model back to Mermaid source. serializeMermaid does not run verification; inspect the result of verifyMermaid before saving, sending or showing the edit. Render only when an artifact is needed.Layout is deterministic for the same source and resolved options. Styles can change paint without changing geometry; a byte diff is not necessarily a layout change.
Return verification findings when an edit cannot be completed. Preserve the previous source and explain the failed operation instead of fabricating a successful result.
Use this loop for existing source edits. New diagrams can start as Mermaid text, and artifact-only tasks can call the renderer directly. See the library reference for both paths.
More in the manual
- Getting started – install, verify, render, and hand a source edit to an agent
- Reading a verify result – the three warning tiers, with fixes
- Rendering to ASCII and Unicode – color modes and terminal use
Docs index
- Start
- Use locally
- Debug
- Reference