Add a Mermaid diagram type
Extend Mermaid conversion with parsing, Excalidraw elements, tests, and playground coverage.
Add a Mermaid diagram type by wiring the type declaration, parser, converter, dispatch, tests, and playground example together. This guide is for maintainers working in the Mermaid conversion package; it does not expand the set of types supported by the hosted editor by itself.
Before you begin
You need a clone of the Mermaid conversion package, Node.js, Yarn, and a Mermaid example that represents the new diagram type. The parser source is under src, and the playground source is under playground. The existing flowchart parser and converter are the closest implementation references.
Understand the pipeline
The conversion boundary has four stages:
The parser extracts relationships and geometry, the converter returns ExcalidrawElementSkeleton values, and the editor utility later turns those skeletons into fully qualified elements. Keep the parser and converter responsibilities separate so each stage can be tested independently.
Steps
From the package root, install dependencies if needed and start the playground:
yarn startThe development server starts on port 1234. Keep it running while you iterate so you can inspect the converted output.
Add the new type to SUPPORTED_DIAGRAM_TYPES in src/constants.ts. This changes the type from image fallback handling to parser dispatch, so the next visible result is an error until the parser exists. Use the exact Mermaid type identifier that appears in the source definition.
Create src/parser/{{diagramType}}.ts and export a function named parseMermaid{{diagramType}}Diagram, following the flowchart parser as the structural reference.
The parser must identify connected elements, arrow and text bindings, and the position and dimensions of each element. Read the relevant values from Mermaid's diagram.parser.yy object and use the rendered SVG for geometry. Return the package's parser data shape rather than fully qualified Excalidraw elements.
Create {{diagramType}}ToExcalidrawSkeletonConverter, modelled on FlowChartToExcalidrawSkeletonConverter, and make it return ExcalidrawElementSkeleton values. Then add a switch branch in parseMermaid that calls the new parser.
A successful conversion now resolves parser data into skeleton elements. Consumers still call convertToExcalidrawElements() before rendering the result in Excalidraw.
Add parser and conversion tests for the smallest valid diagram, a relationship with text, and the geometry or unsupported shape behavior your type requires. Create playground/testcases/{{diagramType}}.ts, using flowchart.ts as a reference. If the type is listed in playground/testcases/unsupported.ts, remove it there.
Reload the playground and run every relevant test. The visible result should be editable Excalidraw elements rather than an image or an unsupported-type error.
Verify
Use a minimal Mermaid definition and confirm that parseMermaidToExcalidraw() resolves skeleton elements, then pass those values to convertToExcalidrawElements(). Verify that nodes, relationships, labels, and positions survive conversion and that the playground testcase renders the same structure.
Troubleshoot common failures
If the type is rendered as an image, it is still absent from SUPPORTED_DIAGRAM_TYPES or the dispatch switch. If registration produces an unsupported parser error, the parser file or exported function does not match the dispatch branch. If elements exist but are misplaced, inspect SVG geometry extraction before changing the converter. If arrows or labels are disconnected, inspect the Mermaid parser attributes used to build bindings. If the playground still treats the type as unsupported, remove its testcase entry from unsupported.ts and reload the server.
Next steps
Read Mermaid parser architecture, then use Convert Mermaid to Excalidraw to verify the public conversion workflow.