Use this page to install the tool and render once yourself. When you hand work to an agent, do not copy a long prompt from this page. Give it three things: your task, the Mermaid source, and one bootstrap line that tells it to fetch the maintained instructions.

Install Agentic Mermaid.
Install the published npm package.
```
npm i agentic-mermaid
```
Create a diagram.
This first pass uses source directly. Add --style watercolor, --style blueprint, or a JSON style file when you render.
```
cat > diagram.mmd <<'MMD'
flowchart LR
  Idea[Idea] --> Draft[Draft]
  Draft --> Review{Review}
  Review -->|ok| Ship[Ship]
MMD
```

Verify, then render.

npx --no-install agentic-mermaid verify diagram.mmd --json
npx --no-install agentic-mermaid render diagram.mmd --format svg --style publication-figure --output diagram.svg
npx --no-install agentic-mermaid render diagram.mmd --format unicode

Hand the edit to an agent.
Paste the task, paste the Mermaid source, then add this line:
```
Fetch https://agentic-mermaid.dev/start.md and follow it.
```
That line is the only prompt to copy from this page. The fetched file tells the agent how to choose library, CLI, or MCP and verify before returning, so this page does not duplicate the protocol.
Copy this line on the homepage
Optional: wire MCP.
Self-hosting over stdio is the default path; a hosted MCP endpoint is also available at https://agentic-mermaid.dev/mcp (streamable HTTP).
MCP config
```
{
  "mcpServers": {
    "agentic-mermaid": {
      "command": "npx",
      "args": ["-y", "agentic-mermaid@0.4.1", "mcp"]
    }
  }
}
```
The config pins the package version shown on this site; npx downloads it on first use.
```
npx --no-install agentic-mermaid mcp
```
Use the installed package over stdio, use the version-pinned config above, or point an MCP client at the hosted endpoint.

Agent style/palette recipe

Keep appearance out of the Mermaid source. Ask the agent to edit structure with typed ops, verify the result, and pass style and palette as render options.

// Library or Code Mode
renderMermaidSVG(source, {
  style: ['ops-schematic', 'nord-light'],
  seed: 0,
  security: 'strict'
})

# CLI
npx --no-install agentic-mermaid styles --json
npx --no-install agentic-mermaid render diagram.mmd --format svg --style ops-schematic,nord-light --output diagram.svg

// Hosted MCP render_svg arguments
{
  "source": "flowchart TD\n  A --> B",
  "style": ["ops-schematic", "nord-light"],
  "seed": 0
}

A style name chooses stroke, fill, typography, and renderer treatment. A palette-only style such as nord-light supplies colors. In the editor those controls are Style and Palette; in API, CLI, and MCP calls, agents can send the stack directly.

Vocabulary

Mermaid syntax support is not the same as Agentic Mermaid edit authority. Use the narrowest accurate verb, and inspect am capabilities --json before an agent claims it can edit or emit a format.

Capability verbs

references: Links to an upstream syntax description without claiming local behavior.
accepts: Recognizes the input and its family header; acceptance alone does not promise structured editing.
parses: Returns a ValidDiagram whose body is typed or whose unsupported source is preserved verbatim.
renders: Produces the requested artifact format; rendering does not imply typed edit authority.
verifies: Returns structured errors and warnings about source, geometry, or quality.
mutates: Applies a declared typed operation to the modeled diagram structure.
round-trips: Keeps typed facts equal after parse → serialize → parse; opaque source stays byte-preserved.

Source and edit authority

Mermaid source: The text the user wrote, including its family header, directives, comments, and frontmatter.
diagram family: A Mermaid grammar and visual form such as flowchart, sequence, Gantt, or architecture.
header: The first meaningful family token, such as flowchart, sequenceDiagram, or architecture-beta.
upstream syntax reference: Mermaid documentation used as authoring evidence, not as a local support claim.
host renderer: The Mermaid implementation and version used by GitHub, GitLab, Obsidian, or another host.
renderer support: The formats this product can produce for a source; consult capabilities rather than inferring host parity.
edit authority: The subset an agent may change safely through typed operations; it is narrower than parse or render support.
structured family: A family whose modeled body exposes family-specific typed operations.
narrow: Resolve a parsed diagram to its family-specific typed surface before mutation.
typed mutation: A schema-validated operation such as adding a node, message, entity, or task.
source-level-only: Content that may be preserved and deliberately text-edited but has no typed operation for that change.
opaque fallback: Lossless preservation used when partial modeling would drop or rewrite unsupported syntax.
modeled subset: The syntax represented structurally; syntax outside it remains segmented or opaque.
round-trip: A check that parsed facts survive serialization and reparsing, while opaque text survives unchanged.
receipt: Reproducible evidence naming inputs, command or tool, warnings, verification result, and generated artifact.

Outputs and evidence

SVG: Vector markup whose element identities, title/description wiring, and sanitized references are checked.
PNG: Raster output derived from SVG with explicit font-coverage and scale behavior.
ASCII: Seven-bit terminal drawing; do not use this name for Unicode box-drawing output.
Unicode text: Terminal drawing measured in display cells and allowed to use box-drawing and wide graphemes.
JSON layout: Machine-readable positioned nodes, edges, groups, warnings, and optional route evidence.
region metadata: Stable mappings from rendered text or geometry back to diagram objects.
structural warning: A model or source-structure problem, such as unsupported or inconsistent content.
geometric warning: A positioned-layout problem, such as overlap, clipping, or an invalid route.
lint warning: A non-fatal source or model finding, such as a duplicate edge or unreachable node.
warning code: A stable machine-readable identifier paired with severity, field, and message.
quality metric: A number such as overlap count or label clearance; it compares layouts but does not explain a fix by itself.
golden: Reviewed expected bytes or pixels used to detect deterministic output drift.
differential fixture: A case compared with upstream Mermaid, another renderer, or a previous implementation.

Configuration and layout

frontmatter: YAML configuration before the Mermaid body; preserve it across safe edits.
init directive: Source-level Mermaid configuration in a %%{init: ...}%% wrapper.
strict security: Static rendering mode that removes unsafe links, external references, and executable behavior.
source order: Declaration order in Mermaid source; preserve it unless a family’s canonical serializer defines another order.
subgraph / group: A container with member nodes and its own bounds; edges may attach to a member or to the container.
anchor: The side, port, or semantic endpoint where a route meets a node or group.
route: The positioned path connecting an edge’s source and target anchors.
trunk: A shared route segment used before fan-out branches or after fan-in branches converge.
fan-in / fan-out: Many incoming edges sharing a target, or many outgoing edges sharing a source.
label corridor: Reserved space that keeps a label attached to its route and clear of other geometry.
display-cell width: Terminal column width after grapheme and fullwidth rules, never JavaScript string length.

Getting started