Mermaid parser architecture
Understand how Mermaid text becomes geometry, connections, skeletons, or image fallbacks.
The Mermaid converter must recover both visual geometry and semantic connections. It parses complementary representations: SVG supplies positions and dimensions, while Mermaid's diagram data supplies vertices, edges, and clusters. The result is converted into Excalidraw element skeletons.
SVG supplies measurable layout; parsed Mermaid data supplies relationships; the converter combines both before returning output.
Parse the source
The entry path processes the Mermaid definition and options, including directives, then calls Mermaid's getDiagramFromText to obtain a diagram representation. A parser is selected for the diagram type. The documented implementation has a flowchart parser, parseMermaidFlowChartDiagram.
This split matters because SVG alone cannot reliably explain which nodes are connected. Parsed Mermaid objects identify nodes and edges but do not contain the final dimensions and positions needed for a drawable scene.
Compute geometry
Mermaid's render API produces SVG. The flowchart parser reads vertex data from diagram.parse.yy, then combines it with the SVG to calculate each vertex's position and dimensions. The normalized result includes an identifier, text, x and y coordinates, width, height, and style information.
Those measurements let the converter place an Excalidraw shape instead of guessing from source text.
Preserve connectivity
The parser reads edges from diagram.parse.yy with getEdges. Edge data describes lines and arrows between vertices. The flowchart converter uses those relationships to create Excalidraw arrows and bindings. Clusters represent Mermaid subgraphs and carry grouping information into conversion where the supported converter can represent it.
Produce output
The converter transforms parsed flowchart data into ExcalidrawElementSkeleton values. The public API returns those skeletons from parseMermaidToExcalidraw; callers must pass them through convertToExcalidrawElements to obtain fully qualified elements.
When the diagram type is unsupported, the rendered SVG is converted to a data URL and returned through an image skeleton. This preserves a visual result but changes the editing contract from individual shapes to an image.
Observable consequences
- A supported flowchart produces editable nodes and arrows after the second conversion stage.
- A special Mermaid shape can appear as a rectangle when no matching Excalidraw shape exists.
- A non-flowchart diagram can appear as an image through the fallback path.
- Invalid Mermaid text fails during parsing, before a reliable skeleton scene is available.
Keep the original source, catch parse errors, and distinguish shape elements from image-backed output. See the Mermaid conversion API and Convert Mermaid to Excalidraw.