mermaid-render

A Claude Code plugin for local Mermaid diagrams: .mmd source of truth → mmdc render → mandatory visual verification → companion markdown note + index hub.

No SaaS, no browser automation, fully offline — diagrams never leave your machine.

Rendering a Mermaid diagram with mmdc gives you a clean exit code and an SVG file. It does not tell you the diagram is right — arrows can point the wrong way, nodes can overlap, a step can go missing, and the render will still "succeed." This plugin's one non-negotiable rule is that a render isn't done until it's been looked at: every .svg gets wrapped in HTML and published with Claude Code's Artifact tool so you and Claude both see it before moving on. See docs/verification-rule.md for the reasoning.

Everything else — the file layout, the companion-note convention, the index hub — exists to keep diagrams and their rendered output from drifting apart over time.

Add the marketplace, then install the plugin:

/plugin marketplace add IT-Explorers/mermaid-render
/plugin install mermaid-render@mermaid-render

Requires Node 18+ and mmdc on your PATH:

npm install -g @mermaid-js/mermaid-cli

If Chromium is missing, add --allow-scripts=puppeteer to that install.

1. Init the project layout — run /mermaid-init in your project root. It creates diagrams/src/, diagrams/rendered/, and copies the default config/mermaid-config.json.
2. Write a diagram — diagrams/src/<category>/<name>.mmd, plain Mermaid syntax.
3. Render it:

   node <plugin-dir>/skills/mermaid-render/scripts/render.mjs diagrams/src/architecture/<name>.mmd

4. Verify it — Claude wraps the rendered SVG in HTML and publishes it via the Artifact tool. Look at it. This step is mandatory, not optional — a green exit code from step 3 is not enough.
5. Document it — add a companion note at docs/<category>/<name>.md (from templates/companion-note.md) and a row in docs/<category>/index.md (from templates/index-hub.md).

See the worked examples under examples/ — pipeline-overview shows this exact workflow as a diagram; project-layout shows the resulting folder convention; session-export-flow shows a real external process (not about mermaid-render itself) modeled the same way.

<ProjectRoot>/
  diagrams/
    src/<category>/<name>.mmd        # source of truth — hand-edited
    rendered/<category>/<name>.svg   # generated — never hand-edited
  config/mermaid-config.json         # shared theme, deterministic rendering
  docs/<category>/<name>.md          # companion note per diagram
  docs/<category>/index.md          # index hub

All three live in skills/mermaid-render/scripts/ and are plain Node — no build step.

Full option list (--output, --format, --open, --root, --source-root) is in skills/mermaid-render/SKILL.md.

Does this send my diagrams anywhere? No. mmdc renders locally via a headless Chromium instance on your machine. Nothing is uploaded except when you explicitly use Claude Code's Artifact tool to preview a render, which is a private-by-default page under your own claude.ai account.

Why not Obsidian-native? The companion notes are plain markdown with YAML frontmatter — they work as-is in an Obsidian vault, but the plugin has no vault-path config or vault-jump behavior baked in. That keeps it useful outside Obsidian too. If you want a note to open straight into your vault, that's a one-line addition to your own workflow.

Why Node instead of PowerShell? So the plugin works the same on macOS, Linux, and Windows without a shell-specific fork.

Can I use PNG or PDF instead of SVG? Yes, --format png or --format pdf on render.mjs and render-all.mjs (validate.mjs has no --format — it only renders throwaway files to a temp directory). SVG is the default because it's the only one you can inline directly into an Artifact-tool HTML wrapper without a data-URI conversion step.

Issues and pull requests are welcome at github.com/IT-Explorers/mermaid-render. The project is MIT-licensed.

MIT — see LICENSE.