Mermaid: Author and Render Diagrams

Overview

Create and verify mermaid diagrams. Mermaid is a text-to-diagram language: fenced ```mermaid blocks in Markdown are rendered natively by GitHub (and most other hosts), so diagrams are committed as text, never as images. The one place an image is produced is local verification — you render the block to SVG/PNG with mmdc to confirm it is syntactically valid and legible before pushing.

Validated against @mermaid-js/mermaid-cli (mmdc) v12.0.0 and headless Chromium 154. Flags are stable across recent releases, but run mmdc --help if a command behaves unexpectedly.

Key insight: the hard part is not the mermaid syntax — it is rendering headless Chromium in a container. mmdc drives a real Chromium browser to rasterize the diagram. Chromium's sandbox requires user namespaces, which are not available to a non-root container user, so bare mmdc fails to launch. A --no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage Puppeteer config is mandatory. The docker-opencode image bakes this in and ships a mermaid-render wrapper that applies it automatically.

When to use / not use

• Use when creating, editing, or verifying any ```mermaid block, or when asked for an architecture / flow / sequence / state / ER diagram in Markdown.
• Don't reach for mermaid when the deliverable is a standalone image file, a C4 model the team manages in a dedicated tool, or a diagram that needs precise manual layout (mermaid auto-lays-out; use a dedicated diagramming tool instead).
• Prefer mermaid over committed PNG/SVG images: it diffs, it is reviewable, and it re-renders on the host for free.

Prerequisites