Mermaid How To Draw

What Mermaid Actually Is Before You Start Drawing Anything

Mermaid is a JavaScript-based diagramming and charting tool that uses text-based syntax to generate SVG images. It started inside GitHub, was spun out as an independent open-source project, and now supports sequence diagrams, flowcharts, Gantt charts, entity relationship diagrams, pie charts, and a few other types. The core idea is simple: you type a description of what you want to see, and a renderer produces a diagram from it. No drag-and-drop interfaces, no clicking to move boxes around manually. The syntax looks like this. A flowchart line reads flowchart TD; A[Start] --> B[End]. A sequence diagram uses participant Alice and Alice ->> Bob: Hello. That is essentially the entire learning curve for the basic cases. Everything else is incremental complexity on top of that pattern.

Mermaid how to draw your first diagram in under five minutes

You do not need to install anything to try it. The official editor is available at mermaid.live. You paste or type your syntax on the left side, and the preview renders on the right. It handles the rendering pipeline internally through the mermaid package and a bundler. For production use inside a website or documentation system, you import the library directly into your project. Here is a minimal flowchart you can paste into the editor right now:

flowchart LR
  A[User] --> B{Decision?}
  B -->|Yes| C[Proceed]
  B -->|No| D[Abort]
  C --> E[Done]

Switch the preview format to SVG, download it, and you have a vector image. That is the fastest possible path from zero to a rendered diagram. The editor autosaves to localStorage, so if you close the tab by accident you usually get your last version back.

How the rendering pipeline actually works under the hood

Mermaid parses the text into an abstract syntax tree, then converts that tree into a directed graph structure, runs a layout engine, and finally produces SVG. For flowcharts it uses Dagre for the initial positioning. For sequence diagrams it calculates horizontal lanes and vertical swimlanes based on participant ordering and message timing. Gantt charts have their own dedicated renderer that handles date arithmetic and dependency bars separately. The output is always SVG unless you specifically export as PNG or PDF through the editor UI. This matters because inline SVG gives you zoomability and accessibility tree integration that raster formats destroy. If you embed the diagram directly in a Markdown file and render it client-side, the browser sees the actual markup rather than an image tag.

Common mistakes beginners make and how to avoid them

The most frequent issue I see is people writing flowchart syntax without declaring the direction. flowchart TD or flowchart LR is required. Without it, the renderer either defaults to top-down or throws a confusing error depending on the version. I spent about forty minutes debugging a diagram that refused to render, only to discover I had written flowchart with no direction keyword and the parser silently defaulted in a way that made everything overlap. Another common problem is mixing node shapes incorrectly. If you use square brackets for a process box and curved brackets for a subshape inside the same diagram, you need to make sure the subshape syntax is enclosed in curly braces with a label. The syntax subgraph mySub[Label] is the correct form. Writing just subgraph mySub without brackets creates an anonymous container, which sometimes works but makes styling inconsistent.

Node IDs with spaces cause parsing failures. A[My Node] is fine because the label is inside brackets, but My Node --> End as an ID will break. Use underscores or camelCase for IDs. Labels can contain spaces and special characters freely.

When mermaid hits real limitations

It does not handle every diagram type well. Complex multi-page Gantt charts with heavy cross-project dependencies render slowly because the date calculation runs on the main thread. Sequence diagrams with more than roughly twenty participants start producing overlapping message lines unless you carefully order them or use the staggGER layout option. The automatic layout engine makes reasonable decisions but occasionally places a node directly on top of an edge, and there is no manual nudging feature because it is text-based by design. Styling is available through a %%{init}%% block at the top of your diagram, but the CSS selectors are internal to the SVG and you cannot inject external stylesheets easily. If you need pixel-perfect brand alignment, you will spend more time debugging the init block than you would designing in a visual tool. Mermaid is fast for rough diagrams and slow for polished ones.

For cases where layout precision matters more than speed, I usually draft the structure in Mermaid to verify the logic and relationships, then export to SVG and refine the positioning in a vector editor like Inkscape. That two-step workflow saves time compared to fighting Dagre's automatic placement.

Version differences that actually matter

Mermaid v10 introduced significant parser changes, including stricter syntax validation and a different approach to subgraph nesting. Code that worked in v9 sometimes breaks in v10 without warning. If you are maintaining a documentation site, pin your Mermaid version explicitly in your package.json or script tag rather than relying on the latest CDN build. The changelog mentions breaking changes frequently enough that assuming forward compatibility is a mistake. Client-side rendering versions range from around 1MB gzipped for the core to 3MB if you include every diagram type. Most projects only need flowcharts and sequence diagrams, so you can tree-shake or lazy-load the specific renderers. Loading all of them at once is unnecessary for typical use cases and increases initial page load time noticeably.

Practical setup for a documentation website

If your site is built with a static generator like Hugo, Jekyll, or Astro, there are plugins or shortcodes that wrap Mermaid and compile diagrams at build time. Build-time rendering produces smaller payloads because the output is already an SVG file rather than requiring client-side JavaScript. The tradeoff is that you lose live preview while editing, but the published pages load faster. For dynamic sites where diagrams change based on user input or API data, client-side rendering is the only option. In that case, you initialize Mermaid with a config object that disables the info tooltip overlay if it interferes with your layout, sets a default theme, and optionally defines a custom themeColors object to match your brand palette without fighting the inline styles later.

I once configured a theme override where the accent color hex code had a typo and the entire diagram rendered in a near-invisible gray because the theme fallback chain failed silently. Double-check every color value in your init block before deploying. The error message it gives you is not helpful.

Where to get it

The library is hosted on GitHub under the organization mermaid-js/mermaid. The official documentation site is at mermaid.js.org, and the live editor is at mermaid.live. The npm package name is simply mermaid. There is no license restriction for commercial use, but the project is Apache 2.0, so you include the license notice if you redistribute the source.